Example:
OK, lets say, and this is my favorite example, you just finished your document, an eight page, single-spaced technical document. And in it you highlight all the important stuff in red. You show it to your boss and he asks ‘Why is all that in gray?’ You tell him why but he comes back with ‘… Red? I’m color blind. Change it all to bold Comic Sans.’ So you have to go through all your documents and change red text.
But lets say, instead, you applied a style. Invent a style if you want, call it Important Text. Don’t call it Red Text, that isn’t abstract and style names should confer a use and not a visual. So instead of coloring the important sections red, you apply this style to them. Important Text may be red if you want, but when the boss needs you to change from Red to Bold/Helvetica all you have to do is just change the style definition and – boom – it’s all fixed up.
Most amateur documentation is cluttered, uneven and doesn’t flow smoothly. Documentation done right is clean, lean, easy on the eyes, easy to read and just the formatting alone can help the reader achieve better understanding of your product. Professional grade documentation is actually very easy to do, just takes a little discipline and a little know-how.
It took me a second to understand this but what my boss told me once upon a time is at the root of Documentation Done Right; he was reviewing the user manual I had written and said “Don’t insert any blank lines — adjust the paragraph style to include space before or after it.”
Ah ha! The germ of an idea.
I had been separating paragraphs with blank lines. Easy enough to do but what if you miss a blank line between two paragraphs by accident! Using blank lines cause questions to immediately come up: ‘when do you use one blank line?’, ‘when do you use two?’, ‘when don’t you?’ When do you use Helvetica? When do I use Times Roman? See — it opens the door to all kinds of inconsistencies.
This even hearkens back to the very first resume I ever wrote. My then boss looked it over and without missing a beat pointed out “That header is indented too far. It is about 1/16th of an inch further in than the rest.” And he was right. As you will see below this would not have been a problem if I had applied the golden rule of documentation.
The golden rule for professional documentation is ‘Only Apply Styles!’.
Conversely, professional documentation has no blank line!
Don’t insert blank lines, don’t italicize text, don’t change font, don’t bold, don’t do any of that; instead, apply a style. And heavens forbid: don’t use spaces (gasp) or tabs to indent text, no, instead you should use an indented paragraph style (say, “SubSection”).
Word and other full power word processors come with this capability and they come with an array of predefined styles. Get to know them; use them, add to them, change their definitions.
If you find you have too many styles then you will have a messy document, restrict the styles to ones that really have real uses.
Ironically I don’t know how to edit the styles in WordPress.
Even web pages in HTML should follow this rule, only instead of ‘styles’ it uses CSS ‘classes’. Just define the style for a particular tag type and/or class and never set the font or attributes in the markup itself. HTML 5 makes this even more-so with semantic tags like <header> and <footer> etc.
Word has an Outline mode which is my go-to method of writing most everything. Styles are applied automatically to section headers based on their level of indentation which is perfect. I just add the styles of Notes and CodeSample and my work is done, at least the formatting work.
If you stick to this rule your formatting will be consistent throughout, you will use fewer styles, fewer fonts (free tip: too many fonts is bad), etc. so the documentation will be clean and uniform and very professional looking.