Documentation – Have a Plan
Have a plan of what you want the reader to understand.
When you start taking notes, you won’t have this plan, and that is okay. Notes are mostly for yourself. But by the time you start to create a document that you want someone else to read and understand, you will need to have a plan on what the reader will take away from the document. Ask yourself, “Is this a ‘how to’, or a ‘how works’ document?”
There is some overlap and subcategories for these two general types, but in basic if you are documenting how to start the system, or documenting how the parts of the system work together, you will use a different approach. There will be some examples in the ‘how works’ document that will be like the ‘how to’ and any good ‘how to’ explains some of ‘how works’ that is inherent in the doing. But these two approaches produce documents that look very differently.
Where is this document going?
As a guide for the focus, (and if you are like me that you have to write documentation in several sittings), place a bold “How To” or “How Works” at the top of the document or where you will see it when you come back to continue with your documentation task. This is just a direction guide. So you will remove this before sharing this document. And it is just a guide, you can still include how to and how works information when you need it to make your point and get the information across that you are trying to convey.
The purpose of your document is …
Another way to keep your focus and direction consistent is to write the summary first. And I do mean first. Lead the document with a paragraph that says, “This document will explain XXXX. When you have read this document you should be able to X, Y and Z and understand Q.” And this is a paragraph that you may want to keep when you are done. It is nice to find a document that gives you exactly what you need. It is even nicer when you don’t have to read multiple documents to find it but just the headings.
Break it down.
After deciding on the direction, and what your target take-away is, you will probably have more than one part. Even if this is just a single page “How To.” So you can now break this out by creating your topic headings. Sections like, “Tools Needed”, “Access Needed” and “Knowledge Needed” are good starters. Pick what applies to you.
If you don’t know what sections you should have, take a look at documentation that already exists and see how it is broken up. This is not cheating. Not only does this solve your problem of coming up with sections, but it can help make your documentation more consistent. And documentation that is in a coherent format with other documentation in the same repository is easier to read and understand.
Subscribe to "The Integration Engineer" by Email
Find out about the tools and services available at The Integration Engineer's Consulting site.
