9.3 How to capture our requirements

There are myriad ways to capture and control requirements from simple text files to dedicated software management systems. You may be compelled to use a specific solution (company standards) but for this project we have free rein. Guided by the idea of maintaining simplicity until we need to make things complex we will start with text files. If future demands require that we use a more complex system for managing our requirements we should be able to reformat them relatively easily (generally I find it easier to move from simpler formats to more complex).

The majority of our initial requirements will be technical. Our users being technical too. That said we may have plenty of non-technical people too; programme office team, often project management is non-technical (or at least not deeply technical). There will also be plenty of people who require information from your project (or providing to your project) that will not be technical; customer, users, human resources, etc.

Eliciting and decomposing requirements is a skill unto itself (just take a look at the many books on the topic; search for ‘requirements’ or ‘business analyst’). But we’ll have a stab at a simplified version.

There are a few things we can be fairly sure about. We need a way to store documentation (including these requirements). The documentation needs to be accessible. Members of the project need to be able to read and update documents. We want to be able to track the history of these documents. We need to be certain that documentation is controlled and accurately identified. I prefer a layered approach to document control.

  • Latest release.
  • Current draft
  • Version control repository

The latest release is the document from which the project must work. It is read only and published for everyone to access.

The current draft is a utility so that the author can access the document. This copy is only required for non-technical authors who cannot (or will not) use the version control repository. This copy may be unnecessary in many projects but my experience has been that it is often a fruitless task to try to get everyone using a version control tool when they have been used to using a shared file system.

The version control repository holds the complete history of all documentation on the project. Depending on the tool used and the nature of your project or organisation you may need to have more than one repository. Some documents may be confidential or restricted. It may be unacceptable to your organisation for these documents to be at risk of exposure (even to other team members—examples include contract and other legal documents, details budgets and costs). My opinion is that project documentation should be release as permissively as possible.

To be clear, the version control repository need not be a specific tool. It is possible to hold all documentation in a set of directories, using file name conventions to maintain a version history.

You should be realising at this point that our requirements need not, and arguably should not, say anything about the final solution (exception being where such a solution is externally imposed).