Post History

Source: https://writers.stackexchange.com/a/5646
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

My experience is in software documentation (particularly programming interfaces), so I'll answer from that perspective. I think these principles are pretty general, but I've never written manuals for, say, airplane repair.

Generally, you want your documentation to say all and only what is needed for the reader in his current context. For example, if you're documenting a programming interface and the signature of the call already contains a return value, typed arguments, and exceptions thrown, don't repeat that -- it's already in front of the reader. _Do_, however, _explain_ any of those that need clarification. What does it mean if it returns null? Are there semantic limitations on the parameters that aren't encoded in the type system (e.g. that integer must be positive)? Are there preconditions (this call is only valid if such-and-such state exists)? These are all cases where you will need to say more, not less, but the point is to not say the stuff that's unnecessary.

This doesn't mean you'll never repeat information. If there are three different contexts in which such-and-such piece of information about your system is important, you need to say it in all three. Whether you do this with duplicate text or via links/see-alsos depends on the specifics of your situation.

Some people approach the problem of concise writing by writing everything down first and then pruning. I prefer to work up from the bare bones. I start with (say) the signature of the call, then ask myself what else the reader needs to know in order to use it, and I write that. (Ideally _I_ will use it rather than just speculating.) The first round of review by the SMEs (subject-matter experts) is focused on whether I left anything out or have any errors; reviewing for the text itself comes later. I've found, by the way, that SMEs are more responsive when I don't drop large rambling tomes on them. :-)

My answer boils down to "don't get verbose in the first place", but what you asked was how to trim down an already-written piece. For that, I go in decreasing chunk sizes (section, paragraph, sentence, word), asking "is this X really necessary?". If not, mark. I do this on paper, not in a text editor, so I can complete the entire review pass before changing anything. I do it in this order because there's no point in tuning a sentence if its entire paragraph or section is going to go away. Do the biggest parts first and then narrow your focus.

I've been talking so far about reference documentation. Other types of documentation, such as tutorials, call for a more verbose style that reinforces previously-taught information. Don't generalize my advice about concise writing to situations where this is not the goal.

Original score: 4