Literature review of software requirements documentation

Software documentation is an integral part of the software development process. However, the process is often challenging because over the course of a software development project the scope can often change and evolve several times with updates and new builds. Despite the challenges that are presented in effectively documenting the development process, the documentation that is produced can serve as a valuable asset that can be used in future projects or future alterations of the current software package. Not only is it important to accurately and clearly document many of the development steps but it is also important to make sure the right people have access and knowledge of the documentation that has been created. Even if the documentation was produced accurately and clearly it is not of much value if it is not accessible or utilized later. This analysis will cover some of the challenges that are present in this process as well as some of the best practices and new developments that can facilitate effective documentation.

Challenges in Documentation

One of the challenges in documenting the software development process stems from the fact that software engineers are generally more concerned with the project and the requirements than the documentation process. This is a reasonable perspective given the fact that the project members are focused making the project a success more so than the documentation process. Therefore the focus is generally on software-engineering related activities and the documentation process is generally an afterthought. Many software engineers find the documentation process as something of a waste of time and relatively meaningless.

Furthermore, another challenge is that software engineers generally receive little training in the documentation process. Generally in schools the course of study is focused on the software engineering skills and again the documentation process is more of an afterthought that receives little attention. Although schools may state the importance of properly documenting a development project, there is generally relatively little time and attention devoted to learning effective documentation skills. In fact, it is commonly the case that the documentation is only produced after the software development project is already completed.

The negligence of the documentation process can be verified by several research studies. One study found that over the course of twenty years of software evolutions in an industrial setting at a nuclear power plant that there were virtually no documented modifications to the source code (Pawlik, et al., 2012). Another study found that professional end-user developers did not voluntarily produce documentation for any modification and only occasionally would even provide a user guide for their work. The most common reason given for not providing documentation or providing only limited documentation is that the developers did not have the time to do so. The second most popular explanation given is that the process is relatively pointless because requirements and design specification were constantly emerging as the project progressed and therefore trying to document the process seemed somewhat futile.

Opportunities

Give the challenges that are inherent in attempting to properly document a software development project, one solution that seems to be gaining traction in the community is the use of a project documentation wiki. Using a wiki to document the processes and procedures for using a software product while the software is still under development allows all development and test engineers and documentation specialists to update the user guide in real time as changes are made to the product (Rettich, 2011). This solution to software documentation has shown to provide many advantages over traditional documentation systems.