Technical Writing

Writing skills are a necessity in many different jobs, including Software Development. While it is one thing to be able to write code for a system, it is another to describe that change in writing. This can include the comments in the code, the check-in comments in the source control, a write-up of the fix in a bug tracking system, or a technical design. Each piece of documentation has a different use and target audience, and the first key for success is to understanding this and to write for your audience.

Inline code comments

Only developers will see your code comments. So feel free to use terms and language other developers world understand. The style, effectiveness and the format of code comments has been discussed and argued extensively. A Google search for "Comments in Code" returns a staggering 472 million results, so I will not attempt to discuss that here. But do remember that your audience can see the code themselves. Your comments will add nothing it they are simply repeating the code. What cannot always be conveyed through the code is why a particular coding method was used and the intent of the code.This is what your comments should explain when necessary.

Check-in Comments

Check-in comments are ained at other developers just like code comments. These comments should be short but informative. It should briefly describe what changed at a high level and for what defect or requirement so if another developer needs to know why a change was made they can reference the defect or requirement.

Defect Report

Defect reports will be read by other developers as well as testers, business analysts, and possibly support people. Writing for this large audience can be difficult at first, but I find the best approach is to write your response geared towards the non-technical folks first, and add more technical information in each subsequent paragraph as necessary. In this way, those who need just the basic information can get the information quickly, while other developers researching your issue at a later date will have all the logical and technical information that you have provided.

Technical Design

While college pretends to prepare yor for the real world, they never tell you quite how much of the time you will spend writing designs. I probably spend between 20 and 30 percent of my time reading or writing designs. The audience of your technical design may differ, but where I work, Developers, Business Analysts, and sometimes Testers will review designs, so the document must be accessible to all of them. Since Defect Reports and Technical Designs share the same audience, the guidelines for Defect Reports apply well to Technical Designs.

General Tips for Technical Writing

Remember that you're not writing the next great novel. Keep the language simple and use the same language or phrase to explain a task multiple times. There is no need to use a thesaurus to make each


10 Outline Document
20 Write Document
30 Revise Document
40 Goto 20

Software Development is unique in that in order to properly design it, you must first determine how to solve the problem. Once you have solved the problem in your head, you can begin to design it, but the process of designing it will reveal edge cases you didn't previously consider, and perhaps you will find places for improvement. Thus, you may find that you need to re-design your solution. The best way to write a technical design document is to follow the above process for a couple of iterations until you are comfortable with the document.


When writing for other developers, it is very useful to know the right terms. Every developer should know the name of common Design Patterns, technologies, and techniques, and using these terms in technical writing can allow the focus to remain on what is important, and not on the details of the Model/View/Controller design pattern.



Technical writing skills are a must for software developers. Unless you are working on a project by yourself, eventually you will need to tell someone else what the code does or what the code will do. However, even if you are the only developer on a project, code comments and documentation may save you if you ever forget why you wrote that dirty little hack in a method buried halfway down in the code base.