What is the role of a Requirements Document?

I have heard a lot of different opinions over the years about what makes up a good requirements document.  What is its value at different points in the process? How does it fit in with more modern Agile thinking?

Allow me to explain the following few “truths”:

1. Natural language is not precise enough to articulate requirements.  If you try to say something precisely, it is not comprehensible. If it is comprehensible, it is not complete. That is why we have code.
2. Neither users nor IT professionals can read any requirements document and judge whether or not it is complete, or even accurate.
3. If anyone thinks a requirement document is complete, they are wrong. No document EVER fully describes the requirements of a system.
4. Users never really engage on requirements (or much of anything to do with a system) until you show them the working system.

Here are some random thoughts:

• If you have a working system and you are building an upgrade to that system, a really good start to the requirements document is the following: “It should do everything that the old system does except get rid of X1, Y1, and Z1, change X2, Y2 and Z2 and add X3, Y3, and Z3…”
• If there is a complex part of the system, you have to describe it in very precise (near pseudo-code) natural language so you can send that to the client.  Then when they complain that the system does not work as agreed, you can reply… “I know that this was a complex part of the system. To make sure there was no misunderstanding, I wrote up exactly how it was going to work. I would be happy to go over the document that you accepted to show that the system works exactly as we agreed.”
• You don’t need obvious requirements in the requirements document such as: “The system shall have a login screen” or “There shall be a back-up and recovery strategy.” Instead, drill down and talk about valid password rules, set up-time requirements and describe the impacts of downtime at various durations.
• In an Agile process, the “Requirements document” is as follows: “Given the state of the system… this is what should change.

I no longer view the traditional Requirements Document to be the linchpin of the development process. Part of the reason for this is that I live in a very Agile development world.  Since our systems are mostly generated from business rules repositories, I am happy to deliver something that is totally wrong… very quickly.  Then, we refactor the system and deliver it again…and again…and again. It typically takes 3-5 times of going through this iterative process prior to the software maturing to the point where the customer is happy.

So, do I still believe in writing down requirements?  Of course. But unless it is contractually or otherwise politically required, I do not support the creation of a traditional multi-hundred page requirements document and using that to drive the system development process.

I have worked on a number projects where I now understand the Agile cry in the wilderness: “Through this work we have come to value…working software over comprehensive documentation.” There is something wrong with the project when 80% of the effort is being devoted to creating documentation, rather than building a working system.