If you're new here, you may want to subscribe to my RSS feed. Thanks for visiting!

I have been in the field of Technical Writing for about twelve (12) years now, and one of the more critical areas is called System Documentation. This is the process of writing meaningful comments in computer code that will help future programmers to understand what has already been coded. Many times, programmers understand their own logic when it comes to programming, but cannot seem to understand the thought processes of other programmers. Therefore, it is imperative for a software application, to have alongside its code, quality comments and remarks that will help the debugging process and future enhancements to the current system.

If I had to give a class or lecture about writing system documentation, these are the suggestions I would give to the attendees:

1. Be pragmatic with your coding. As I mentioned above, many programmers understand their own logic, but cannot understand the logic of others. It is always good to program with a conservative style so that others can understand what you are doing.

2. Be consistent with comments. Make it a rule to place your code comments and remarks either before or after your code, consistently, throughout the program. This will save the reader the confusion of having to relate the comments to the right piece of computer code.

3. Use colors when coding. Most programming tools today use standardized colors for unique aspects of the programming language, like keywords, reserved words, functions, etc. This makes it much easier to interpret the code and generate meaningful comments that can be used to generate future HTML help files that are based on the system documentation.

4. Be consistent with your comment style. As a programmer, you should be able to logically determine the best way to “slice the programming pie” so to speak. As you appropriately divide the program into parts, in your comments, this will allow readers to see how the different modules correspond and the readers will also follow your comments more easily as the program progresses.

5. Learn XML. Within the Microsoft Visual Studio Development Environment, for example, XML tags can be used for you to generate, in the program compile, an output XML file that can give you a basic system documentation of your program code. There are not that many tags you need to use, so in a few days you should be able to master this.

6. Pseudocode counts. Most programmers like to work directly off specifications, but I personally believe that pseudocode is a blessing. There is always an intermediate step between the program specifications and the actual writing of computer code. This is known as pseudocode, which is a re-phrasing of the specifications to make the coding process easier.

7. Check Documentation Generator options. There are a few documentation generators out there, such as NDoc and Doc-o-matic, which can help you greatly in your efforts to generate a quality system documentation. Open source programs are free and usually written by highly creative and talented individuals. Proprietary programs are usually well-documented and have live support for their products.

8. Anticipate language changes. As time evolves in the computer industry, so do languages. So, as you write comments and remarks, try to capture the essence of the task that the code accomplishes, as opposed to really nit-picky interpretations of the low-level aspects that you are using. Make sure your comments “interpret” the code and that it becomes portable, if necessary.

9. Consider system limitations. As you code, make sure that what you are developing is able to run on the machine of your customer or client. So, as you code and create your comments for the code, make sure you specify these aspects of your code and the necessary system requirements to run the application. You don’t want any unnecessary crashes.

10. English is the best language for documentation. As you code and create meaningful comments for your code, try to do this in English because the most important operating systems and programming languages are English-based, and business-wise, English is the most universal language in terms of portability. If comments had to be translated, English is the easiest language from which comments can be converted into other languages.

Tags: Writing //