Documentation continued

5 thoughts
last posted Nov. 12, 2013, 6:08 p.m.
0
get stream as: markdown or atom
repost from Documentation by jml
0

Writing something out is an immensely valuable mental exercise. I find it clarifies thought, reveals areas of ignorance, and exposes assumptions.

But writing something for someone else? For a total stranger? That is both much more work and a very different kind of work.

0

jml started a good series with some documentation themes earlier today; I figured I'd contribute another few ideas. The most immediate one comes up as a further point to the reposted card: your documentation should be based on where the other person begins

To clarify that a bit: find the crossover between implicit and necessary knowledge. "Setting up a vhost", for instance, presumes knowing what a vhost is

(this can be catered to the so-called target market consumers of the thing you're documenting)

0

Explain the motivation/reasoning. Understanding why a thing is the way it is becomes a powerful stepping stone to using it better

0

Something to aim for is to impart knowledge, not information.

The latter is best found in reference manuals. The former is the thing that will allow a person to use your tool/product/whatever.

0

"Documentation is where information goes to die", to steal a quote from jerith.

Make sure that you revisit what you write in documentation as often as you revisit the thing you're changing.