Writing technical documentation is required task for many developers. Once you start producing documentation you quickly learn good documentation is more than just screen shots. You will be required to write and express complex concepts. Documentation can be very challenging. Especially if you are not comfortable writing for non-technical users. It is a skill like any other. It can only developed through practice and experience. Here are a list of tips and ideas which I have used for writing effective documentation.
Practice Writing
Above all else, the more you practice writing the better you will be. When I left college my writing was not up to par. It did not improve until I started practicing. My writing may not be perfect, but it has shown vast improvement, because I practiced writing. Many ways exist for you to practicing writing documentation. Here are just a few that I used.
- Start writing in a blog about technical material you interested in.
- Document your own work. You can use a personal wiki. TiddlyWiki is one example.
- Just sit down and write anything. Just write.
Read Other Documentation
Reading documentation is a way to broaden your knowledge of documentation. The more you read the better writer you will become. Reading other documentation can help you learn a learn from other’s successes and mistakes. Here are some ideas for reading other documentation.
- The O’Reilly Books great example of technical documentation for Programmers and Administrators.
- Documentation of technical tasks for non-technical users.
- Find similar documentation to the technical item you want to document.
Know Your Audience
Before you ever start writing, ask yourself who is my audience? This sets the stage for the tone of the document and how the information should be presented. Here are a set of questions to clarify who your audience is.
- What technical skills do my users posses?
- What terms will make your users comfortable or feel uneasy?
- What reading level are your users?
- Are they comfortable with technical writing?
- Do they understand the non-technical aspects of the task?
Be Consistent
Keep your documentation consistent. Consistency reduces the barriers to following a complex idea. It increases readers comprehension of the document. Here are some tips on consistency.
- Use consistent jargon ex: If you call a link by the term hyperlink, do not use the term link later.
- If you are adding to a document try to follow the existing writing style.
- Use a consistent writing style.
- Use consistent and proper spelling.
- Use the same font styles consistently.
Write Clearly
There are many ways we can clarify documentation. Technical language is sometimes a necessity, but that does not have to effect the clarity of our writing. Here are some tips for making your documentation slightly more clear.
- Define jargon and acronyms when they are introduced.
- Do not skip steps when documenting tasks.
- Highlight problem areas, potential pitfalls, and common mistakes.
- Provide concrete examples.
- Use the simplest words that work.
- Avoid complex and run on sentences.
- Use paragraphs to isolate larger concepts.
Efficient For the Reader
The only thing worse than incomplete documentation, is inefficient documentation. Writing an efficient document goes hand and hand with clear documentation. Do not make your users search through loads of documentation. Make the important points stick out.
- Good headlines and Sub-Headlines will allow your users to effectively scan content.
- Good section grouping will allow users to find similar concepts quickly.
- A search function for online documentation is extremely effective. I recommend using a Wiki.
Conclusion
These tips will not make you a better writer over night, but they can help you become more cognizant about what you are writing. Below are a list of tips and resources to help with writing documentation.
