Skip to main content

Technical documentation in a team using Scrum methodology.

Last post 04:16 pm July 31, 2017 by Pablo Cruz Navea
5 replies
06:31 pm July 27, 2017


I'm working in a team that is migrating from cascade to scrum (big change), there are some problems I'm facing that is that there's none documentation applied to specify technical matters of the system we are working on.

I came here to get some advice on how can I implement a good, concise and complete technical documentation of the system. So that, new joiners to the team can easily access this docs and avoid doing a full debugging of the system to correct some bugs.


08:38 pm July 27, 2017

Hi Juan,

One thing that comes to mind is this line from the Agile Manifesto:

Working software over comprehensive documentation

I'll assume you read the Agile Manifesto and still see this documentation as important, but my first question would be does delivering this documentation offer greater value than other items that can be worked on?

I'll now assume the answer's yes and (to make it simpler) I'll also assume the whole Development Team and Product Owner are in agreement.

Presumably you've managed without documentation already, so I don't expect there is a sudden need to have everything documented immediately. In any case, however high the priority of this documentation, Scrum can help you.

The Development Team may include maintaining documentation as part of its definition of "Done".

The Development Team should do this if it finds the documentation worthwhile, and helpful in ensuring quality. Specifically, if included in the definition of "Done", the Development Team would take responsibility for writing/updating documentation to an agreed standard, whenever a new software Increment is produced.

For documentation of existing functionality, perhaps each page/chapter/topic could be added to the Product Backlog. I would expect the Development Team and Product Owner to communicate, so that the Product Owner can prioritize this work appropriately. Like any work done by the Development Team, this should be estimable, and the Development Team able to get it to "Done".

02:25 am July 28, 2017

Thanks Simon,

In response to your first question, my answer is really yes, but I'm interested to know what you mean with other items to work on.

Take in mind that we are working on a huge system, therefore lots of people involved (not only dev team) like functional analyst to mention one.

04:22 pm July 28, 2017

You can think of the production of documentation as either a matter of scope or of quality. There may be a mix of both on an initiative.

If a document is something the Product Owner values, and can prioritize in relation to other Product Backlog items, then it may be seen as constituting scope. Its production may be planned into a certain Sprint and delivered as part of that increment. 

If a document is something the Development Team believes is necessary in order to properly sustain its work, then it is more a matter of quality. They may plan relevant development tasks into their Sprint Backlog in order to produce it, even though the PO may not necessarily care about it and it does not figure on the Product Backlog. If such a level of documentation quality must apply to each and every increment, then the Development Team may assert that adequate documentation must be produced in their Definition of Done. 

04:29 pm July 28, 2017

Please bear in mind that within Scrum, Development Team is one of the 3 defined roles. It does not have to just include 'developers'. This team could include coders, testers, analysts and more, in order to 'develop' a new Increment of the product.


There's always a way to add value to the product you're working on, and one of those ways is to write documentation; but normally there are many other ways to do so, like adding new functionality or fixing bugs.

I don't know the specifics of the system you're working on, but consider two situations:

1. you have a website that people can use, but nothing is documented about how the website works, how to use, or how to support it.

2. you have an extensive document that explains every single aspect of how the website works.

Which do you think is more valuable?

Sure, they do both have value, but only the undocumented website achieves what it is supposed to do.

So the ultimate question is should improvements to the product wait until all of the documentation is written? 

Within Scrum, it is the Product Owner's responsibility to set priorities, and you should do what makes the most sense; this could be writing documentation, testing, developing new features, or bug fixing; but the specific priorities of these should be managed, so that you are constantly working on the most valuable improvements to the product.

08:25 pm July 30, 2017

Juan Manuel, you started wrong with the title. Scrum isn't a methodology, thus you're wrong making an equivalence between Scrum and no documentation. 

First, remember Product Owner discusses with Development Team issues about Product Backlog items. In this discussion, it is perfectly valid to explain the PO why it would be valuable to have documentation (e.g., for maintainability purposes). You just have to convince him/her.

Second, if you work in a strict environment, the Product Owner will probably have in consideration the required documentation as part of the Increment that will be the output of the Sprints.

Third, in case in which you're trying to initiate a documentation project, personally I think Scrum is not the best alternative. Just adapt a process based on the iterative-incremental model and voilà!



By posting on our forums you are agreeing to our Terms of Use.

Please note that the first and last name from your member profile will be displayed next to any topic or comment you post on the forums. For privacy concerns, we cannot allow you to post email addresses. All user-submitted content on our Forums may be subject to deletion if it is found to be in violation of our Terms of Use. does not endorse user-submitted content or the content of links to any third-party websites.

Terms of Use may, at its discretion, remove any post that it deems unsuitable for these forums. Unsuitable post content includes, but is not limited to, Professional-level assessment questions and answers, profanity, insults, racism or sexually explicit content. Using our forum as a platform for the marketing and solicitation of products or services is also prohibited. Forum members who post content deemed unsuitable by may have their access revoked at any time, without warning. may, but is not obliged to, monitor submissions.