

Where Did All the Documentation Go? - techdog
http://asserttrue.blogspot.com/2009/03/where-did-all-documentation-go.html

======
mustpax
Article hints at this, but different applications require different approaches
to documentation.

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.

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.

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.

------
mechanical_fish
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 _still_ famous for writing excellent product manuals, but
now they're called "the Missing Manual series" and you must buy them _a la
carte_.)

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 _in the car_ and _drive_ to a store and _buy_ 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 _telephone_ 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.

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.

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 _far too many_ 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
_less_ 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 _disappear_. (e.g. _The Merb Way_ \-- 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.)

------
uggedal
For those in need of inspiration have a look at Django's documentation:
<http://docs.djangoproject.com/en/dev/>

------
adoyle
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.

------
ableal
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.

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.

Now, however, there's nothing really preventing help-on-demand, instead of
stop-and-go-dig-it-up elsewhere. Except, of course, the expense ...

~~~
diN0bot
exactly. i couldn't get into this article because it all hinged on a single,
un-qualified assertion. what kind of documentation for what kind of projects?
i don't see "documentation" going away, but my personal perspective is
obviously limited to my own realm of software.

