Overcoming “Requirements Writing” Block

by Krishna on August 23, 2007

Here is a fact of life: When given a development task, most developers directly jump into coding with the bare minimum of understanding or documenting the requirements. This happens despite the common knowledge that lack of proper requirements management can derail the project and result in an application that has little value for end users. But everybody keeps doing the opposite. In the past, I have been no exception, either.

Why do developers do this? One fallacy about lack of requirements documentation is the thinking that perhaps programmers do not know the value of requirements enough. Such an argument holds as much weight as saying that people don’t quit addictions like alcohol and smoking because they don’t know about the harm caused. People are intelligent enough to understand the benefits and costs of something, but it is very difficult for them to change what they are doing even with that knowledge.

So what are the possible causes?

  1. Developers don’t know how: Many developers have no idea how to write a requirements document, let alone a good one. Many times, developers are asked to document the application they have already created. But they don’t know how to create a document directly from the end users. Sometimes, the developers are aware of the standard requirements template (like the IEEE template), but don’t have any experience in filling it out.This lack of knowledge creates several mental blocks. Without understanding what is involved, the developer feels that the task of collecting requirements will take a long time. He or she may feel incapable of handling the task. The software developer may not know where to begin. Also remember that it is not just documentation; it also involves activities such as customer interviews, system analysis and study of existing documentation.
  2. Coding produces a solution, requirements doesn’t: When you code, you produce a tangible program that can be demonstrated to customers and end users. When you write requirements documents, all you get is a document and you still need to spend the effort on coding. Hence, there is a feeling that writing requirements “wastes time” that could have spent on coding. Plus, many programmers feel guilty when they go through periods of not coding. It feels like idle time.The reality is that requirements document save time in the long-term by avoiding misunderstandings and helping programmers code without spending time trying to figure out what the users may have wanted. Adding new project members can also be less painful because they can read through the documentation. But such considerations are not immediate enough and people go for instant gratification.
  3. People cannot figure out a happy medium: One reason why many people hate requirements documentation is that they don’t know how to create documentation that is just sufficient for development needs. Sometimes they create too little, which is useless for practical development purposes. Such a document becomes shelf ware. At other times, people create too heavy documentation, which is very difficult to navigate or maintain, thus creating more resentment.There are 2 primary audiences for requirements documents — the customers (to validate) and the programmers (to code against). It is very difficult to satisfy both sides. If you make it detailed enough for programmers, customers don’t have the time or patience to validate the document. If you go in the opposite direction, you find programmers making unwanted assumptions. In short, creating a requirements document is very tough.

Education is not the solution. Providing examples and opportunities for developers is the better path. Here are some tips:

  1. Lead by example: If you have never created a requirements document yourself, it is difficult to tell people what it entails. You should try creating requirements documents that suit your organization and the type of projects that you do. You can start with existing standard templates, but quickly customize them to your needs. Liberally use feedback from others in your organization. After all, they are the ones who are going to be using it regularly.
  2. Give small assignments: Get people to be comfortable with writing requirements by giving them small analysis tasks before they start coding. Do not give tasks that go beyond more than a few hours. Also try to provide instant feedback when the write-up is provided to you so that the developer doesn’t feel he or she is losing time in completing the work. Remember that the first few times a developer does this, they are likely to make more mistakes and take a lot of time to get it right.
  3. Facilitate and encourage analysis and design: Coding can be fun at times and you can perform cool tricks with various programming techniques. But much of coding is really cruise control. You know what you have to do and you just do it. And that is why people just dive into coding — the flow is more natural. Thinking is tougher. And hence, you need to actively force people to spend time on analysis and design so that they can get used to thinking and brainstorming. Once they get used to it, they may like it better than coding.
  4. Avoid religion: CMMi and Agile have diametrically opposite views of documentation. Organizations may follow either and that is their prerogative. But requirements documentation should not be the slave of one particular school of thought. A requirements document is the lifeline for the development team. Follow what works. If it is less than or more than what your methodology specifies, so be it.


Kalpesh August 24, 2007 at 9:56 am


I think the role can be better performed by someone who understands domain of the customers & enough of technology

It is more of translating the needs of business into an application.

I understand that developer should be involved, so that they can understand the domain as well as suggest technology guidelines, if need be.

In a product based company, a product manager would do this.

Rakhi December 18, 2007 at 3:02 pm

Typically this is done by a Business analyst since they know the business side/clients as well as have enough technical knowledge

Krish December 18, 2007 at 3:51 pm

Rakhi, thanks for your comments.

I have addressed this issue in another post: Specialized Requirements Analyst. Please take a look if you get a chance.

Comments on this entry are closed.

{ 2 trackbacks }

Previous post:

Next post: