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 check the following training courses: ‘Business Analysis’ ‘Requirements Gathering & Specification’, ‘Technical Writing Skills’. Full details at www.irm.com.au.
By Derrick Brown. Adapted for the web by Phil Dean. 2002 IRM Training Pty Ltd ABN 56 007 219 589. www.irm.com.au.
Phil Dean is Operations Manager for IRM Training, Australia’s premier training provider for Business Analysts.
