I recently completed an analysis of several requirements documents within an organisation – the documents covered similar areas of work and were covering similar types of requirements, so there was a common thread between them. The documents were, as one would expect, compiled by different individuals from differing teams.
Half way through this review process, I was struck by the poor quality of the documents. The requirements were generally vague and in several cases the bulk of a document comprised of large data definition (DD) tables that had been simply copied from another source. I also became aware that the only hope for getting the correct solution developed by the software development house is if the developers themselves have an in depth knowledge of the environment and can fill in the blanks and improvise for the lack of content.
I had initially thought that the poor quality was limited to certain authors, or groups, but quickly saw that all documents shared this common thread.
It was soon apparent that teams that work closely with one another tend to have commonalities of how things are done and this was being carried through into the composition of documents, which were sorely lacking.
As an outsider to the enterprise, there was no way that I could use the documentation to get an understanding of what was built and the docs now only served to make the auditors happy by acting as a paper-trail, but having little substance beyond the introduction.
When faced with this problem of complacency, I find the following steps useful to self-moderate your own documents to ensure that they make the grade:
- Read the document as though you are an outsider. Not everyone has an innate knowledge of the environment and these documents are used by the developers to build but also by internal staff as a reference point.
- Give reasons as to why things are done in a particular way. We all know that office politics run rampant, but the reasoning and justification behind why something must be built a specific way is useful when you’re reviewing last years requirements or trying to analyse where a project went astray. If you don’t know why things are done in a particular way, then ASK.
- If you’re documenting the rebuild of an existing process, don’t just state that it needs to work & function the same way – that’s a cop out! Reference the original requirements, and if those don’t exist, then start documenting them – the requirements need to be laid out at some point, and now is as good time as any.
- Get some peer review going, especially for larger or more complex requirements. The academic world relies heavily on peer review and for many good reasons. Don’t be afraid to get critical feedback – it will improve the quality of your future work and also helps to share knowledge within the team.
