It’s that time of year. I keep more than I should, but now and again you have to clear things out. I don’t promise to dispose of all of these though: they remind me of another era, when software came in huge boxes packed with books.
If you purchased Microsoft Office, for example, you would get a guide describing every feature, as well as an Excel formula reference, a Visual Basic reference and so on.
If you purchased a development tool, you would get a complete language reference plus a guide to the IDE plus a developer guide.
The books that got most use in my experience were the references – convenient to work on a screen while using a book as reference, especially in the days before multiple displays – and the developer guides. You did not have to go the way the programmer’s guide suggested, but it did give you a clue about how the creators of the language or tool intended that it should be used.
Quality varied of course, but in Microsoft’s case the standard was high. When something new arrived, you could learn a lot by sitting down with just the books for a few hours.
What happened to manuals? Cost was one consideration, especially as many were never opened, being duplicates of what you had already. Obsolescence went deeper than that though. Manuals were always out of date before they printed, especially when update distribution was a download rather than a disk sent out by support (which means from the nineties onward).
Even without the internet, manuals would have died. Online help is cheaper to distribute and integrates with software – press F1 for help.
Then add the power of the web. Today’s references are online and have user comments. Further, the web is a vast knowledgebase which, while not wholly reliable, is far more productive than leafing through pages and pages trying to find the solution to some problem that might not even be referenced. In many cases you could post a question to StackOverflow and get an answer more quickly.
Software has bloated too. I am not sure what a full printed documentation set for Visual Studio 2013 would look like, but it would likely fill a bookshelf if not a room.
When software companies stopped sending out printed manuals, the same books were produced as online (that is, local, but disk-based) help. Then as the web took over more help went to the web, and F1 would either open the web browser or use a help viewer that displayed web content. There are still options for downloading help locally in many development tools.
Nothing to miss then? I am not so sure. It strikes me that the requirement to deliver comprehensive documentation was a valuable discipline. I wonder how many bugs were fixed because the documentation team raised a query about something that did not seem to work right or make sense?
Another inevitable problem is that since documentation no longer has to be in the box (or in the download), some software is delivered without adequate documentation. You are meant to figure it out via videos, blog posts, online forums, searches and questions.
A good documentation team takes the side of the user – whether end user, developer, or system administrator, depending on context. They write the guide by trying things out, and goad the internal developers to supply the information on what does and does not work as necessary. That can still happen today; but without the constraint of having to get books prepared it often does not.
Unit tests are the documentation. So some say 🙂
Documentation has gone to hell in a hand cart. Microsoft used to have good online documentation under MSDN, but even that is a complete mess, often with out of date alpha/beta stuff that isn’t labelled or dated as such and leads the naive “user” up the garden path. MVP blogs are worse. Helpful articles for RTM don’t exist because bloggers desperate for MVP renewal have already moved onto the next alpha release. Online video training doesn’t work. It takes hours and even if slide decks are included for reference they’re useless because the idea of “a picture speaks a thousand words” seems to have eluded modern trainers as they instead just “sit in the IDE in real time” in the gold rush to get another course out the door as quickly as possible for royalties from Pluralsight and the like. These days you can pretty much guarantee a course will be out of date within weeks if not days with the constant stream of updates and changes and seemingly untested fixes and endless dependencies. As for Stack Overflow… Really? Too often the correct answer is way down a long list of incorrect up-voted replies from those desperate to get recognition while the real answer is ignored because people don’t know enough to understand the question, let alone the proper answer and what constitutes a “bad hack” vs a properly thought out solution.
In the last few weeks I’ve had something like six new releases of Angular, most of which have included breaking changes, Trying to explain that to a customer paying for development “just write the code. What’s the problem? Why does stuff have to be continually rewritten to get around breaking changes?” is “fun” (not!) and would be so even if the appropriate documentation were there (it never is in my experience) This is all apparently great progress because everything but everything MUST be done “agile” fashion. Agile is great, but shouldn’t automatically be used for everything. God help us all!
Manuals? Heck, I can’t even get CD/DVDs anymore with my dev tool (Delphi)
Ah, I remember the pile of manuals that came with our Amstrad 1640 – 5 for the word processor Locoscript with one dedicated to printer settings!
I miss the logical layout and progression of a good manual; it’s the reason why I still treasure my books on coding as I’ve found them to be far better than simply looking up what I think is the immediate problem on Stack Overflow.
There’s another thing that you miss when you don’t have a manual – the sense of anticipation and excitement about using a program. I know that opinion varies about their products (I like them) but Magix has always produced manuals that made me excited about using the software.
Ahhh I have fond memories of the big boxes that contained Foxpro 2.6 and Delphi 1,2 & 3.
It was almost as if those things were value for money given the size and weight of the products. I still like to read ‘real’ reference material just like I still read physical magazines and books. Just because I spent hours coding doesn’t necessarily mean I want to be sat in front of a screen reading help too.
Still good for the environment I guess!