There are whole books written about technical documentation writing. Here are my key take aways.

• Make sure you know who the audience is before you write a single word. You are writing documentation for others, not yourself.  Put yourself in their shoes.
• Use terminology the reader will understand.
• Use short simple sentences. Long sentences get confusing when describing complex concepts.
• Always define a term or acronym before using it. For example, “in a Service Oriented Architecture (SOA) …” Then use “SOA” from then on.
• Examples should never be underrated, just like pictures.
• Avoid using too many different fonts or styles unless there is purpose in doing so. It confuses the eyes more than it helps.

When writing a document, I always start with an outline. I have a series of bullet points that I think through and get the order of right before I start on the main text. Editing a document to change its structure is painful. It requires careful review of all the text written to make sure the flow has not been lost. Getting the structure right saves a lot of time.

I personally find you get to the point where complex edits are faster done by rewriting a section. Small edits are fine. Large edits get painful.

Documents, like programs, have structure!

• The first chapter of a book should be an introduction, the last a conclusion.
• The first section if a chapter should introduce that section (and nothing more). A final concluding section sometimes is useful.
• The first paragraph of a section should summarize the section. A final paragraph might be suitable as a conclusion – to summarize and highlight the main points.
• The first sentence of a paragraph, very importantly, state the objective of the paragraph. This allows skim reading down a document. It also is important for editing later – you can work out the purpose of a paragraph from its first sentence, making reordering easier.

Just remember that writing technical documentation can be done top down like programming.

With respect to styles of manuals, when writing a suite of documentation of a large system I recommend

• A documentation roadmap – describes all the manuals and their purpose so readers always have a single starting point. It’s like a home page.
• Reference documents should list all options in excruciating detail. Javadoc can be used where appropriate. Examples are always valuable.
• User guides should leave the reader through common paths or use cases. They don’t talk about all features. They are a guide to get people started. Later when experts, people can read the reference material to work out all the options. They should have real working use cases.
• Training documentation tends to be similar to user guides, touching on key points but not covering everything. Exercises are worth twice the value of reading material. We learn by experience.

What to write documentation in? There are Wikis of course, but I like manuals being under version control with the product they are documenting. Markdown looks interesting here, otherwise latex, doxygen, etc – with binary formats such as Microsoft Word a last resort.