Structuring Documents, Or Making it obvious

One of the complaints that people have about technical documents is that they don't "hang together"--that the material seems like a bunch of separate items. Often, that's the case: You may not need to worry about making it all hang together ("cohesion") if, for instance, you're writing a user manual for a software product. In that scenario you often end up discussing disparate features (topics) where (a) the topics don't have much to do with each other and (b) you don't expect the audience to read the topics together.

It's when you're working on more sophisticated explanations (whitepapers, for instance) where you expect the audience to read a substantial part of your document in the order that you present it that "making it all hang together" becomes important.

Your best strategy for achieving cohesion is, of course, to organize the material in a way that makes sense to your audience: To match the order that you use to cover the topics to the audience's world view. I often see documents that, as part of their introduction, describe the purpose of each section and why the sections appear in that order. If the audience is expected to read the material straight through (perhaps skipping the odd section that covers material the audience is already familiar with) this is useless material: The reader will never remember past page 10 what the purpose of section four is or why it belongs between sections three and five.

I often get the feeling that, in these introductions, the author is trying to convince the reader that this organization makes sense. The time would have been better spent determining how the audience would expect the material to be presented (perhaps by looking at the organization structure of well-regarded documents on similar topics that are read by the audience). In a book, given how few people read introductions, the time spent writing out these explanations is probably wasted, anyway. Rather than put the explanation for the organization in the introduction, the author would be better spent converting that explanation into into section headings where audience members can actually see it.

A well-structured set of headings tells the audience what each section is and demonstrates how the sections fit together--headings make the structure of your document visible. Headings are how audience members find their way through the document (skipping what they don't need to focus on what they do need).

So what are the rules:
1) A heading for a block of text should unambiguously tell the reader what's in the block of text
2) Where you have several topics (with their headings) grouped into a section, the heading for the section should describe what links the topics together.

Reverting to user manuals: In a car's user manual, for instance, you would expect to see this kind of structure:

Dealing with Problems with Your Car
     Engine Light On
     Weird Rumbling Noise from the Dashboard
     "Thwup-pa, Thwuap-pa" Sound From Outside the Car

And so on.

One last note: A heading is only useful to your reader if they can see it--if the heading stands out from the body text. A heading must be 33% larger than the text it accompanies for the human eye to see it as definitely larger (i.e. if your body text is 12 point, then your heading must be 16 point to be seen as larger). Section headings must be 33% larger than any subheadings to show that they are "more important" than their subheadings.

To stand out, headings must also be in a different font than your body text. If your body text is a serif font, put your headings in a san-serif font (and see Robin Williams Non-Designer's Design Book for more--and better!--advice on formatting).

Reading or read

• A Criminal to Remember by Michael van Rooy
• Yiddish Folktales by Beatrice Weinreich