4 ms·
It's a shame that most manuals have evolved to web pages that you can't download as PDFs or eBooks. Now you usually have to go online to find that keyword, and
by ASalazarMX 6y ago
It's a shame that most manuals have evolved to web pages that you can't download as PDFs or eBooks. Now you usually have to go online to find that keyword, and as you're online already, might as well google for the whole answer.
One of the most productive times in my career was programming for the IBM i in the 90s. There were manuals online, but you could also download indexed PDFs versions. IBM did a superb job with their documentation, there was hardly any need to look up anything in the Internet, whatever you needed was in the manuals, examples included.
Of course you still used the Internet at work, but mostly for mingling with your peers and having technical discussions, although too many people still blindly copied/pasted from the forums.
- ralusek 6y agoThat's interesting that you say that because I actually have the opposite reaction. When I go to look for documentation and find that it's a PDF, I want to die.
- ASalazarMX 6y agoPDFs are horrible as eBooks, but in a manual I prefer the fidelity of a PDF than the reflowing of an ePUB, or the fickleness, slowness, and potential unavailability of a web page. A well structured and correctly indexed PDF is a godsend, because you just open the table of contents, quickly locate what you're looking for, click and there is your answer. As I said, IBM excels at writing documentation. Every language has a Language Reference manual, and a Programmer's Guide manual. The first is for reference, the second is to learn how to use it, including examples. Don't take my word for it, you can check out, for example, the COBOL manuals here: https://www.ibm.com/docs/en/i/7.1?topic=languages-cobol https://www.ibm.com/docs/en/i/7.1?topic=languages-cobol
- ghaff 6y agoI think it depends. For something well-structured like a cookbook I'd prefer PDF in most cases. But it really varies. For example I find most guidebooks do a decent job of Kindle these days and have actually switched over to a significant degree because it's really useful to have everything on my phone.
- afiori 6y agofor this specific use case a single html file that you open in the browser might be the best option (at least php offer that option and I appreciated it).
- bluedino 6y agoThe first PDF I had was a 'bonus' book that came on a CD included with a programming book. There was a compiler along with sample code from the book, and then something like SAMS Teach Yourself Visual C++ in 21 Days. I absolutely hated it. My screen was only 640x480, so I could barely see a whole page, much less see my IDE at the same time. These were the days of single 14 or 15 inch monitors, not dual or triple 24" widescreens. It was also a little on the slow side. Early Pentium, 8MB RAM, 4X CD-ROM... These days I'm delighted to see a PDF. There's a table of contents and index, they're searchable...copy and paste usually stinks, though. PDF's are forever. They print nicely. They don't get lost when the project upgrades a major version, you can still use them when there's a DNS issue with your ISP, you can use them when you don't have internet...
- agallant 6y agoYou may be interested in https://devdocs.io https://devdocs.io (offline-friendly documentation tool). And if you prefer a straight up desktop app - https://zealdocs.org https://zealdocs.org
- milkytron 6y agoI also really enjoyed Dash when it was free to use: https://kapeli.com/dash https://kapeli.com/dash
- jabo 6y agoWhy not pay for it or get your employer to pay for it, especially if you enjoyed it?
- ASalazarMX 6y agoThank you. I've used it, although it adds a lot of complexity for the same features than a folder full of manuals would give. I'm probably too set in my ways, but I prefer references that are always available offline. Devdocs.io once in a blue moon would forget about my choices, and I would hate to redownload them.
- sammorrowdrums 6y agoI once downloaded Python docs as an iPad app and a small Python IDE - I was working on a cruise ship and so offline documentation really helped. It taught me to get better at reading the Python docs, but more importantly to cope better without being able to just search every issue I was having online.
- airstrike 6y agoMy first programming experience was with mIRC scripting and it was ridiculously convenient to have everything in a nicely written a local, offline .hlp file https://www.mirc.com/help/html/index.html?mirc_scripts.html https://www.mirc.com/help/html/index.html?mirc_scripts.html I remember spending the afternoon tinkering with it until late at night when dial-up "logic" meant I could finally go online without it costing an arm and a leg