2016 12 21

Author: Jurij Čiževskij

As Agile methodologies became very popular nowadays some traditional software engineering activities were blindly reduced. This brought many projects to failure or at least to the state of being challenging.

One of such activities it is documentation of requirements. Agile manifesto states that working software is more valuable than comprehensive documentation which is completely true. Though it should not mean that there are no documentation.

To document requirements teams usually use User Stories and sometimes Acceptance Criteria which contains not comprehensive information about system behavior and interaction with users.

It often leads to:

  • Misunderstanding between a team and a client,
  • Estimations are not realistic,
  • Developers request additional details during sprints (which means multitasking, lateness and so on),
  • Details and alternative behavior are not deeply analyzed so change requests and additional development is needed,
  • etc.

You can read some insights on this topic in the article “Why I still use use cases” written by Alistair Cockburn (one of the author of the Agile manifesto).


Let us be agile not only managing software development but also in deciding how comprehensive documentation should be. Here is particular project specifics analysis and some tips which can help to decide on how detailed documentation should be to mitigate risks and bring benefit to software development projects.


There are well built teams which cooperates well. Each one knows his responsibilities, there is a clear leadership structure, relationship inside is healthy and supportive and team have been working together for some time. If a team is immature or newly built, then documentation can help to agree on what needs to be done so that less analysis bugs, disagreements and relationship problems may occur. Have you ever seen quarreling between QA and development on functionality? Usually clearly documented requirements before implementation is started helps to reach agreement.


During few decades IT has invaded into many business areas if not to all. Technical people and even business analysts or product owners hardly can have all needed business domain knowledge to provide the best solutions. There are teams who works within one domain for a long time and this makes them great in understanding their clients. But have you seen many of such teams? Especially custom development companies faces this issue. More comprehensive documentation acts as additional well organized knowledge warehouse which makes life easier.


If all important stockholders are collocated (especially in one room) then it is much less trouble with requirements and understanding. Let us be sincere, this happens rarely. One of the biggest issues software engineering and specifically requirements management faces is that most valuable and needful stakeholder who can provide real requirements are the busiest ones. Wise set of documentation that is provided by small parts can help to reduce the load on such persons who barely can be available anytime.


Some projects are big enough to have two or more teams involved. This adds additional communication and additional risks of misunderstanding. It is a good solution to have these teams to be allocated together for at least some time which is required to build better relationship and common understanding of functionality. Otherwise more detailed documentation can help to mitigate risks of analysis and communication issues.


Relationship between development team and business has significant impact on a project and especially on requirements management. I have worked both with clients who have trusted team as partners and professionals who help them to achieve their business goals. Such cases are most enjoyable to work with. We still documented requirements but for other reasons. Also I have been working for the government institutions where people usually afraid to take responsibility and institution goals are not in the first place. Sometimes organizations have people who are not interested in a project or have no interests in its success. Add here regulations and revisions and you will have great need to document functionality and solutions before implementation.


This point is related to the previous one. If communication between business and IT is easy, each one understand goals clearly and there is a trust between partners, then it is more flexibility in documentation. Requirements might be communicated faster and easier. Some solutions can be trusted to IT professionals. There are less arguing and more adequate decisions. If communication is limited to very official meetings which developers really “likes” then we do not have good collaboration (which by the way another important statement of the Agile manifesto – Customer collaboration over contract negotiation).


We have already talked about the importance of having business involved to requirements elicitation process. I have seen amazing business owners who understand IT impact on their business and spend a lot of time communicating with a team. They are regularly available and proactive (though they can be even from another country). If they are not then business analyst or product owner who is sophisticated in using requirements structuring and documentation techniques can easily provide information in an attractive / understandable way to involve business to the process.


As we can see the reality is not so perfect… Relationship between people are complicated and hard, there is much data in the world so people can hardly keep even the smallest part of it in the mind, during globalization projects has multi-geographical and multi-cultural environment. Documentation as a part of software engineering has occurred to solve specific issues. Yes sometimes it goes to extreme. Agile can help to bring balance by applying “working software over comprehensive documentation” approach. Let us understand project environment specifics and be agile on deciding what level of documentation is just enough to give benefit and do not put software itself into the shade. We should not forget the important remark of the Agile manifesto: “That is, while there is value in the items on the right, we value the items on the left more.”. Hope this article will help you to be agile and more effective.