Developers Challenges on Requirements and Documentation

II will be talking about how software requirements are important for developers. Here I put software requirements in a agnostic project methodology ( Agile, Waterfall, or V-Model) view. If you are a developer or manager, for sure you have hear the following statement:

” Our project documentation is poor, it is complicated to understand the requirements.”

Couple months ago I hear this, and I talked to the team to align what was the problem, in this case was an expectation regarding the level of the detail inside a specification. Which we solve by increasing the verbose on the tasks (User Stories, if you prefer.). So this one was easy for the analysts (P.O.). But to take action to solve it by getting this from a retrospective or a water-cooler talk is the key.

Listen and understand the development team is not easy task when mix different cultures, styles, and personal expectations. So take time to put things on track. But worth it!

I read the Stackoverflow 2016 software development survey and the same complain shows up. Well it is more common than I thought. It is quite obvious, however from the numbers there are a significant quantity of developers complaining about documentation and requirements.

Over 75.000 devs (0.4% of overall users of stackoverflow) de 20 a 34 years in USA and Europe classified challenge the following three things:

  • Poor Documentation
  • Unspecific Requirements
  • Changing Requirements

To enrich this discussion and see it in another point of view I will describe below the strategy how to identify the problems related to this context using the PBSRS method. It will give you an example of directives of how to deal with this scenario.

First Step, Analyzing the Context

The context depends on several attributes[2]  and your company context is different from mine. Thus I will propose a hypothetical context that is familiar to me. I recommend to see the Kruchten (2007) work to map your context.

My hypothetical context here is:

“A company has a strong difficulties to effectively specify the requirements for the software development team. Developers complain about poor documentation, unspecific requirements, and changing requirements.”

Step two, Define the Mitigation Actions or Customer-Problems

From this context we can translate the following actions to mitigate or try to mitigate the problems statements:

  1. The Software Development Manager must ensure the existence of software requirements specifications available for Developers , otherwise excessive learning-curve will be generated and extra rework may apply.
  2. TBD (Other action problems can be derived here.)

Step-three, Define the Software Needs

(TBW, I will write this part in my next time.)

Step-four, Define the Software Requirements

(TBW, I will write this part in my next time.)


ReqDev – As manager can we build a Req-Dev approach? It is a analogy to DevOps movement that clear recognize the need of developers and operation work together to increase value and streamline the processes in contrast of push and pull mode.




[2] Kruchten, Philippe. “Voyage in the agile memeplex.” Queue 5.5 (2007): 1. Available in: 10.1145/1281881.1281893

[3] Problem Based SRS, Souza, Rafael Gorski M., and Paulo Cézar Stadzisz. “PROBLEM-BASED SOFTWARE REQUIREMENTS SPECIFICATION.” Revista Electronica de Sistemas de Informaçao 15.2 (2016): 1.