During elicitation the requirements engineer will not only hear goals and desired characteristics of the future system/product, but also desired characteristics of the business process or of the business organisation. In the case of external development, desired characteristics of the development process – including requirements documentation – will also surface. All these desired characteristics are valid and must be captured. I think that it would be a mistake, though, to have them all in one and the same document – the requirements specification – be it a document or a section in your requirements management system. The requirements specification shall contain solely desired characteristics on the future system/product. It describes the future system and is the basis for the design and test of the system.
This is according to the principles:
- a document shall contain information about only one subject
- a document shall be directed to a well-defined audience
- each item of information shall be stored in only one document from the beginning to the end of the project.
Applying these principles results in packaging the other desired characteristics to different documents.
Goals are a stakeholder's (i.e. a person's or an organisation's) description of the benefit intended in the context of the system. They are the economic justification for the projects, and the project success is measured on achievement of these goals. Because they pertain to the project and are needed for the decision whether the project shall be carried out at all, they are best stored in a document called "project charter" or "business case".
The envisaged benefit will be achieved by adapting the business processes and, if needed, adjusting the business organisation to the reshaped processes. (For this discussion we neglect projects whose benefit is in cheaper IT infrastructure and have no intention of changing business processes.) The obvious approach is to capture the reshaped business process in a new version of the document where it is described already. Standard Operating Procedures, documentation of the quality management system, instruction manuals, etc. are examples of such documents. A new version shall be prepared at the beginning of the project – even before the requirements on the supporting systems/products are specified – but will be published for general availability only once the system/product is completed. However, during development they serve as a basis for acceptance tests.
The expected documentation and the characteristics of the development process depend on how the project is carried out. Such descriptions are the fundamental content of a project plan. Independent of where the desired characteristics originate – internally or externally – they should only be described in one document: the project plan. There is only one approach to the project.
I think that throughout my career I have placed the requirements on all subjects – process, project, and product – in their respective documents and that I have not violated the principles I've stated above. I don't mind how the documents are designated, but I do get nervous when I see the information about these different subjects kept in the same document: it is not maintainable, it is reader-adverse and it is evidence of a lack of separation of concerns. I don't know which is the worst!
Figure 1 illustrates the role of the requirements engineer in filtering the elicited information and directing it to the right container. This ensures that the right people obtain the information needed for their work.
I doubt whether I've caught all kinds of desired characteristics on all subjects. I have no doubt however that applying the above principles will help to decide where the information belongs in case I've missed some.
P.S: Thanks to Oliver Hoeffleur/INFOGEM who shared first my doubts and helped me to express them more sharply. Thanks to the reviewer for very helpful comments.