Saturday, March 7, 2009

Quality of Software Documentation

Explain why the success of a system depends heavily on the quality of the documentation generated during system development.

Let me begin by quoting (as closely as possible) one of my previous instructors: “Anyone can make software but not everyone can justify what they created.” This is what one of my previous instructors told us about the difference between a “programmer” and a “software engineer”. Being just a programmer is simple- you just code and create a program. But, being a software engineer or developer is harder because they have to make the program and justify what they did by documenting the software. So why is documentation so important in the success of a system? I found four reasons that sums it all up.

First, documentation acts as a communication medium between members of the development team. Even in the early stages of development, documentation should already have begun. It is necessary to keep track of everything that the team has come up with, decided on and used or done. Sometimes also, the members of the development team are unable to meet face to face and there may be a gap in the communication among the team members. The documentation fills in this gap. It allows the team members to keep track of what the others are doing.

Second, documentation is a system information repository that is to be used by maintenance engineers. In the usual scenario, the development team is different from the maintenance team. When the time comes for the system to be updated or repaired, the maintenance team can use the documentation that came with the system to troubleshoot and perform maintenance properly. Since they were not the ones who developed the system, they don’t have the initial knowledge to maintain it. The documentation contains the necessary information they need to know about the system to repair it or do some upgrades.

Third, the documentation should provide information for management to help them plan, budget and schedule the software development process. Like I mentioned earlier, the documentation process should start early in the development. This includes the initial plans, budget and resources that the management can allocate to the project. Documentation in this sense also serves as a justification of the resources spent by the management on the project. The documentation allows them to see the progress of the project.

Finally, in most cases, documentation should tell users how to use and administer the system. Users are usually ignorant of the system at first. Therefore, instead of them having to call the developers and ask them about how the system works, they can just check that documentation that came with it so that they will know how to administer the system initially.

Unfortunately, much computer system documentation is badly written, difficult to understand, out-of-date or incomplete. Although the situation is improving, many organizations still do not pay enough attention to producing system documents that are well-written pieces of technical prose.

Document quality is as important as program quality. Without information on how to use a system or how to understand it, the utility of that system is degraded. Achieving document quality requires management commitment to document design, standards, and quality assurance processes. Producing good documents is neither easy nor cheap and many software engineers find it more difficult that producing good quality programs.

No comments:

Post a Comment