Technical documentation serves as a repeatable communications medium. That is, written so that anybody reading with the appropriate competency will come away with the same conclusion.  Not filling this gap or relying upon verbal communications has great limitations. Many of us have likely played that game as children where a group of people line up in a line.  The first person whispers something into your ear and you whisper that into the next person and so on until you get to the end of the line. Seldom does the input verbiage resemble the output.  Additionally, there is no traceability of this verbal exchange.   In this regard, documentation synchronizes the objective and the work of the team.  So we understand what we mean by technical documentation, we provide a few examples:

• Requirements
• Software Design Documents
• Configuration Management Documentation
• Test Plans

The skills required for this work may not be exactly the same as that of the developer or person writing software.  Writing software is not about clearly articulating a concept but achieving the feature or feature set of the product.  Clarity is also required for writing code, but it is not the same objective of the documentation.  To that end, some developers may not have the requisite skills or the motivation to sit down and write this type of documentation. For example, when you write code, you can fairly quickly see the fruits of your labors. When you write documentation, it may be some time before you see the results as the document itself may not be considered the fruit of the labor but the product may.

Sometimes it is not the developer with reservations.  Organizations typically want to see results quickly.  I have seen organizations pressure the staff to quickly make progress and one of the first things to go can be this documentation as some believe, erroneously, that documentation adds little value to the process.  Sort of like commenting the code, which under the best circumstances may not be so necessary. The problem is, the best circumstances are not so frequent in occurrence.  Like anything, there is a spectrum or range of scale of documentation, from no documentation, to excessive in which the laws of diminishing returns are in place. That is the increment in the amount of documentation is more costly than to not have that increment of documentation.  This threshold will depend upon the costs, type of product and associated risks.

The way to get better, like so many things, is to study, practice, and collaborate.  For studying, there are standards from IEEE from which the developer can learn about documentation.  The items below provide a few examples of the up front documentation typically associated with software development and is not exhaustive. Though these may be dated and have some superseding document, this can give you a starting point:

• IEEE Std. 1233-1998 IEEE Guide for Developing Systems Requirements
• IEEE Std. 830-1998 IEEE Recommended Practice for Software Requirements Specifications
• IEEE Std. 1016-1998 IEEE Recommended Practice for Software Design Descriptions

These standards provide descriptions of what “good” looks like and are a source from which we can learn and adapt to fit our product and organization’s needs.  Armed with this input, we are then able to set about doing the work, practicing.  This is predicated upon the organization’s recognition of the benefit, though. There must be some line and project management level of support that recognizes this documentation is necessary.  Finally, we move to collaborate.  Documentation is not the sole answer to quality product development. Poor or errant documentation is as bad if not worse than no documentation.  Documentation reviews find problems early and are one of the biggest benefits.  We find problems when we are thinking it through and can be fixed by editing text or graphical models as opposed to up-rooting or cobbling onto the code.

In many organizations, this technical documentation is the kernel from which the customer documentation will grow. Doing so assures us to a greater degree that the product customer documentation matches the actual product features.

Great documentation synchronizes the project and the team from beginning to end.  We are all working from the same script so the chances of us working in technical conflict or at cross-purposes withinthe team are reduced. Additionally, rather than discover this technical conflict during the work, we are in a position to review the documentation before we start working to ensure we are on the same page. Then either the developers modify their approach, or the documentation is modified to better suite the entire scope and objective of the development.  It is much easier to fix documentation in the early phase and then to start development and converge the design work verbally.