Where Did All the Documentation Go?

Article hints at this, but different applications require different approaches to documentation.<p>For applications geared towards "expert" users, well structured reference documentation is essential. This is true for programming languages, development frameworks, professional sound/video/image editing tools and some enterprise applications. Users of these applications perform complex tasks and are invested in their tools enough to educate themselves about them in some capacity.<p>Consumer oriented web apps on the other hand should gravitate towards in-context documentation, tool tips, help icons etc. If your users cannot figure out the most common tasks through discovery, you're not going get any adoption. No amount of documentation can change that. Granted, reference documentation can still be very useful in this case, but it's usually better structured as an FAQ or some other troubleshooting/cookbook oriented manner.<p>Succinct documentation still needs to be well written. Please don't let your software engineers write end-user oriented documentation. And I'm saying this as a software engineer myself.

The answer isn't mysterious. Some documentation has moved online. The rest has gone private: You buy it at Amazon, often from the same tech writers who used to write the "free" documentation that was built into the price of your product. (e.g. David Pogue used to be famous for writing excellent product manuals, and he is <i>still</i> famous for writing excellent product manuals, but now they're called "the Missing Manual series" and you must buy them <i>a la carte</i>.)<p>This used to be impractical because the Internet didn't exist. When you brought your copy of Microsoft Excel home from the store you needed a printed manual because, when you couldn't figure something out, your alternative was to (a) get <i>in the car</i> and <i>drive</i> to a store and <i>buy</i> a third-party manual and take it home, only to discover that it sucked and you needed to repeat step (a) again; (b) get on the <i>telephone</i> and speak to tech support people, perhaps slowly and haltingly, with no graphics or screencasts to help you; (c) pray that you had a local expert from your company's IT department; (d) give up, take the software back to the store, and buy some software with a better manual. It was the threat of option (d), and the extreme cost of servicing option (b), that drove companies to expend a lot of energy producing manuals.<p>Now we have lots of alternatives: Google, wikis, official forums, unofficial forums, blog entries from power users, Stack Overflow. And browsing and buying third-party manuals can be done from your desk, thanks to the power of sites like Safari Books and Amazon.<p>My impression is that the "unofficial" web-based options, combined with the third-party manual market, works fine for software that doesn't change frequently. (e.g. Photoshop -- my only problem as a Photoshop newb is that there are <i>far too many</i> manuals and tutorials available and I'm suffering the paradox of choice: I can't decide which to try first!) The big, new problem is that the Internet has sped up and de-synchronized software development to the extent that the docs can't keep up. I work with Drupal, a product that evolves so fast that the documenters can't work fast enough: they must produce and organize the docs for the older version, the latest version, and the up-and-coming version (which are all significantly different). And Rails is far <i>less</i> stable. I own a bunch of Rails books that are two years old, and they're increasingly obsolete. Given the lead time in producing books, you can't even get the damned things out the door before the products they describe <i>disappear</i>. (e.g. <i>The Merb Way</i> -- if Merb doesn't actually disappear after the Rails merger, it will certainly be a different platform, with a different audience, than the book authors were predicting six months ago.)

For those in need of inspiration have a look at Django's documentation: <a href="http://docs.djangoproject.com/en/dev/" rel="nofollow">http://docs.djangoproject.com/en/dev/</a>

Maybe a little OT: there was a time when you would get complete schematics for hardware you bought. I remember getting reams of circuit diagrams for DEC computers and peripherals. DEC also had great little handbooks with info on how each I/O register in the interface cards worked. Of course, those were also the days when their field service engineers would show up with an oscilloscope and a soldering iron to fix your computer.

Good, thoughtful piece. I have one hopeful thing to say: for good software, maybe the documentation is tending to get 'built-in' in the form of tooltips, "what's this" links, etc.<p>That was out of the question, due to resource limits, a couple of decades ago - you were fighting to fit just the bare functionality in the code, and shipping the explanatory details on paper.<p>Now, however, there's nothing really preventing help-on-demand, instead of stop-and-go-dig-it-up elsewhere. Except, of course, the expense ...