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.

• The Elements of Style
• Introduction to Technical Writing/Documentation
• OWL (Online Writing Lab at Purdue)
• Software Documentation via Wikipedia
• Key for Effective Documentation

Bookmark It

The content of subversion comments can vary depending on what is being checked in. My conclusion is that content of the comments should be functional. One can go into great detail, or be fairly abstract. This should still be left up to the person making the comments, because with software development we work at different levels of abstraction depending on the situation.

The template I am looking to establish is a general guideline to provide a consistent format for a revision control log that allows us to quickly scan it. If we can scan quickly, and understand what happened we get an idea of the history of certain section of our repository. Here is a breakdown of what should be included, and how to describe it, and how to prefix your subject.

Type of Commit         How to commentand 'Prefix'           the commit ==========================================================================

Bug Fix                1. Describe the problem'Fix '                 2. Describe the fix

New Feature            1. Describe the new feature'New'                  2. Described anything that had to change

Change Feature         1. Describe the change'Update'               2. Describe where the change was made                       3. Describe anything anything that was impactedHousekeeping           1. General description of what changed,'Clean'                   and why.

Fix XML Output Display

1. My example node was not being included.2. Changed logic in GenerateNode() to include this node by default.

Bookmark It