Limits of Documents
A typical programmer’s experience with traditional requirements is working from a document written in dry, formal language, that describes a desired software system. By studying this document, s/he gradually builds a mental model that guides the development of an executable software system. The requirements document acts as both means of communication and data storage (preserving evidence of the request). When you put yourself in the place of this programmer there are several flaws with the use of documents as a communication medium that you are likely to encounter. Documents are selective and unidirectional; they may also be ambiguous, vague and conceal gaps.
Documents are a one-way communication medium; information flows from author to reader. There is no opportunity for the reader to ask questions, offer ideas and insights. The author may try to anticipate questions but cannot realistically be expected to address everything and in an attempt to cover everything, a concise abstraction may be lost in a forest of pages.
A programmer working from a document is likely to find parts of the document difficult to understand. This may be due to poor choice of words by the author or lack of reader’s background knowledge. How does that programmer get to the bottom of the intended meaning? In a corporate context, s/he may not have met the author and the normal channel for questions will be correspondence via email, which takes time. If working under time-pressure a programmer may make their own conclusion about the intended meaning to avoid delays. Getting answers to questions takes time but guessing the answer can lead to developing the wrong software system.
From the author’s perspective, there is likely to be a delay between writing a document and receiving questions from readers. Any gaps spotted by readers will require the author to update the document. Documents take effort to maintain with significant ceremony to sign-off each new draft. This makes it possible for documents to fall out of step with current agreed working understanding of system requirements.
The author writes from their personal perspective on the system under development and naturally makes assumptions about the background knowledge of the readers. Requirements documents often describe what is required rather than why – outlining a desired solution rather than explaining the problem space. Little is said about the needs of the users and business context surrounding the system development. Following traditional development process it is assumed that the programmer does not need to know this information because requirements are chosen purely on business grounds. The job of the programmer is limited to the technical implementation of a system rather than contributing ideas on how to achieve business benefits. However, during the implementation many micro-level decisions will be made by the programmer, an awareness of the system context could help with these.