For about 11 months now I’ve been at my current employer. One of the things that has been different in that time is that the development team has had, and been able to request clarification on, software specifications. In tribute to my experience with specs, I’ve decided to blog about my thoughts on them. By no means is this intended to be a comprehensive review of software specs. If you want that, read Software Requirements 2 by Karl Wiegers.
Specs are so much more than documentation on how the system should work. In addition to providing a strong foundation for the development of the intended software, specs will allow for the resulting software to be thoroughly tested, comprehensive documentation to be written and the development of training materials. Probably the one thing that I’ve seen thus far that out ways any other benefit of having good specs has been the ability to use them to control scope creep.
Like any document, a software spec is only as good as the content it contains. Not only does the content needs to be comprehensive and accurate, but the document also needs to be constructed in a searchable, scalable and readable format. Because software specs can, and should, be used to create so many additional documents they also need to be written so they do not cater to any one specific role in the software development process/team. Software specs also need to practice good encapsulation to ensure that contradictory specs don’t exist and, so that when the inevitable change requests start pouring in, the changes can be made in one location.
Document formatting is a finicky thing, even if it isn’t for specs. Everyone has their own idea of what is best. Regardless of the decided format, the document needs to be clear. If possible, segment the contents of the document into sections using the formatting power in MS Word and then use the Table of Content feature to create a searchable outline. In the end, decide on a format and refine it when necessary. Even if the format is not perfect (few things ever are) maintaining consistency will go a long way to ensuring communicating effectively with the spec’s intended audience.
The contents of software specs will vary depending on the type of system and the type of contents being spec’d. Software specs might include any number of things. For example, a UI spec document may include information on control tab orders, data entry validation, and data display formatting. The one item that seems to be missed regularly from these documents is a section that outlines what to do in exceptional circumstances. When we create software specs and envision the system at it’s completion, we don’t think about how to handle situations that may break it. Always ensure that there is a section outlining these situations and how to handle them. If you think that there aren’t any, review the spec again because you’ve probably missed some.
The real reason for writing the software spec’s is to facilitate the transfer of knowledge between people in different roles during the software development process. You must know the audience that you are writing the document for. Yes, it could be read by anyone in the end, but if you write it for the broad audience it will not be informative enough to be helpful to the primary audience. Imagine trying to read a document meant to describe business process and practice that has been written focusing primarily on the technical implementation of said business process. It wouldn’t be informative to a business user and possibly would cause more confusion then it would answer questions.
One of the ideas of OOP is encapsulation. This may be the one case where business can apply programming practices to it’s daily work. By robustly encapsulating software spec’s, the writer offers distinct segmentation of the information provided by the specs. Encapsulation of spec documentation will also reduce the possibility of specific items existing in multiple places with multiple contradicting definitions. General, system wide specifications should be defined centrally and those spec documents should be referenced rather than the information repeated.
If you disagree with what I’ve written or if you have something to add, leave a comment or drop me a note.