Software development is a complex process. As ideas are converted into actual code, the ability to alter the overall design is drastically reduced. Reworking ideas on paper is easy; however, rewriting many lines of code is inefficient. By providing detailed software development documentation early on, you can allow for sweeping changes in the design of the application.
Specs and requirements
Specs and requirements should be drawn up early on to define exactly what the application must accomplish. These documents will both guide the construction of the code, and allow for the development of thorough tests.
For more information on writing specs and requirements, see the following technical writing resources:
- Writing Software Requirements Specifications
- Painless Functional Specifications - Part 1: Why Bother? (Joel on Software)
Technical writers can often assist in the process of developing specs and requirements by acting as usability advocates. By working through the specs, a writer can look for complicated processes that might cause user confusion, and help design ways around such pitfalls. Early interface work is especially ripe for a technical writer's skills.
I've found a great resource for software development document templates, including design documents, functional requirements, test plans, and more.
Abstract code and comments
When the specs are nailed down, initial coding is often done in an abstract language. An abstract language allows programmers to deal with the logic of a program without worrying about the details of a specific language. This abstract code is often turned into code comments as the real language-specific code is written.
Comments in the code are another area where technical writers can assist the development process. By reviewing the comments, a technical writer can clarify any confusing details, or look for missing information that would help future maintenance of the code. However, a writer will need to work closely with the developers to ensure the accuracy of their changes.
Well-commented code is essential for maintaining the application. Future programmers will depend on comments in the code to understand its purpose and structure. Also, comments are necessary for sharing information about dependencies and any expected input that the code needs to function.
Most development teams hold frequent meetings to discuss the design of software. Meeting minutes can be a valuable source of guidance for the development process. This is another area where technical writers can assist in the design process. By taking accurate and detailed meeting minutes, a technical writer can ensure that design plans are clearly recorded for later reference. Also, assisting in this fashion allows writers to have a more thorough understanding of how the application works when it comes time for writing documentation.
As you can see, software development documentation serves an important role in the design process. Writers can use this opportunity to leverage their skills in a way that benefits the entire team, and gain a deeper understanding of the functionality of the software.