Was Your Last Software Specification Really Appreciated?
If you are still trying to write system specifications in English then you are in trouble. For the same reason that engineers and architects use graphical tools to specify their products so too must software specifiers (the term software engineer may be used, but it does imply that we're using a disciplined approach).
A system needs to be broken into small pieces in a structured way and we need to show various views of the system and how they fit together. Typically we may show a process view, a data view, perhaps a time-line view. Each piece, or module, can then be specified, using the following rules:
1. Structure the specification – use a numbering system. Number each separate business rule. User acceptance tests can then be devised and cross-referenced accordingly.
2. Cross-reference – your specification must cross-reference to the basic processes of your process model.
3. Your headings should include:
• Overview
• Input files
• Output files
• Files referenced
• Processing rules
4. Write in the present tense, not the future. It's easier to write, easier to read, and it makes more sense as it will be read and used more when the product exists.
5. Write from the viewpoint of the processor, not the user.
6. Be crystal clear and unambiguous. Use the active voice (subject, verb, object, sequence), not passive voice (object, verb or verb phrase, subject, sequence).
7. Test the specification – before it gets to the developer!
8. The rules of clear writing apply. In addition, do not use words like should, could, may, can, might, as these lead to ambiguity. Do not use automatically – a computer process by definition is an automatic process – that is what you are specifying.
For further information visit the IRM Training website at a
www.irm.com.au and check the following training courses: Business Analysis, Requirements Gathering & Specification and Technical Writing Skills. You may reproduce this article as long as the following is included:
This article written by Derrick Brown and adapted for the web by Phil Dean. Copyright ©2002 IRM Training Pty Ltd.www.irmtraining.com.au
