Chapter 19: BEING SPECIFIC Writing Software Specifications

• I’ve never known any trouble that an hour’s reading didn’t assuage.
• Used correctly, specifications oil the development process.
• Not just the existence, but also the quality of software specifications is vital to the software development process.
• Specifications are an important communication mechanism for software developers. Use them to capture information that must not be lost or forgotten.
• With all important facts written down, there’s less risk when people leave the project: The amount of information loss will be minimized, and there will be a solid base to help any replacement programmer get up to speed.
• All information is conveniently recorded in a known place. New people can join your project and understand what each component does and how they fit together, just by reading the documentation.
• The requirements for a project are never clear at first; customers can’t tell you exactly what they want their software to do (they’re not computer experts, so they don’t know).
• The customer must agree to and sign off on the requrements specification; it forms an effective contract between the software developer and its client.
• When the requested software is finally built, the customer realizes that what it asked for wasn’t what it actually wanted: Rewrite it in pink.
• Sadly, many software factories skip requirements gathering or do not give it sufficient import. It’s vital to agree on the requirements early on, before software design has started and certainly before any code has been written.
• Software requirements must be captured early to set expectations, to prevent feature creep, and to reduce developer angst.
• If your software task is not adequately specified, don’t start coding until you’ve written a functional specification, and people agree that it’s correct.
• Use literate programming tools to write your technical documentation. Don’t write a word-processed document that will quickly go stale.
• If a specification can be interpreted in more than one way, then the “specification” isn’t specific—it’s not doing its job.
• An effective specification is inviting to read and easy to understand.
• The best specifications are written from the perspective of the reader, not the writer.
• A specification should be self-contained and complete.
• The contents of a specification must, therefore, be verifiable.
• Nothing is set in stone, neither code nor documents.
• Think about the contents of your specification as you write it. Choose a structure and vocabulary that the audience will understand, and make sure that the document is correct, complete, and self-describing.
• Writing usually works best when there is one author per document.
• The author must be the right person. e.g. The marketing department doesn’t write your functional specification;
• Each document must have a defined owner who takes responsibility for it.
• Document review is important
• Once you’ve finished the specification, don’t forget about it. Keep it alive and up to date.
• Saving time by avoiding specifications is almost certainly a false economy; specifications help to save time communicating. When you write a specification, you only have to describe how the program works once. If you skip this step, at least the same amount of communication happens anyway, but on an ad hoc basis—over a longer space of time and in a less controlled manner. This communication is far less effective and will actually take longer, because you will have to explain the same things over and over again with a slightly different spin for each audience.
• It is dangerous and unprofessional to avoid writing specifications. If there isn’t enough time to write a specification, there probably isn’t enough time to write the code.