As part of the audit and compliance for my company (PLC), any Agile Projects are treated as a normal Waterfall Projects for review purposes although run according to Scrum best practice. We don't interfere in the process, we simply treat them equally for compliance.

How much software documentation is reasonable for an Agile Team to produce whilst working to fortnightly Sprints?

The new Scrum Master balked at any documentation and we seem to have settled upon documenting any aspect which has the risk of impacting another departments dependency.

(In short - if they break something that is not theirs, they have some documentation to back up the process, intent and reasoning).

How much documentation would you expect a Scrum Team to produce working within a Multinational Corporation? Current tools in use for administration are Confluence/JIRA.

The primary rebuttal against in-depth documentation was that

  • It needs factored in as a User Story and given a points value (which I accept)
  • It ruins the flow of the developers work (also accepted)
  • Documentation is out of date within a week because of code changes/improvements etc (which I do not wholly accept)
  • Documentation is contained within the code (Which I have rejected outright as worst practice)

My concerns are

  • In 3,5 or 10 years time a new developer might require documentation
  • Having read Code Complete and been a Front-End Dev I was taught to document
  • Agile purists use the "working software" principle as a shield for no docs
  • Compliance with external auditors, internal governance and shareholder value

I hope I have provided sufficient detail for someone to answer or guide me in my learning. Have any writers touched on this aspect?

My hopes are that

  • A piece of software can extract code comments and package them as a report
  • The Scrum Master is just being protective but a consensus can be reached
  • Opinion: The effective scrum team should be more focused on creating GOOD unit tests and achieving a high code coverage ratio rather than bulk documentation -- in the long run it's more productive, and (via the mantra of "self-documenting-code" enthusiasts) there is a bit of overlap there. -- New developers brought on to the project can immediately see if they broke anything, and how things are meant to work. -- They can fix bugs confidently without worrying about breaking existing functionality or regressing already fixed bugs, etc. -- Each unit test should have comments describing the test. Commented Aug 13, 2014 at 5:34
  • 1
    @BrainSlugs83...that sounds great apart from the Scrum Team are not en entity into themselves. They are part of a larger whole that has to answer to an enterprise level audit. We don't let hardware engineers produce hardware without documentation; I struggle to see who software developers should be exempt because it might inconvenience their thought process. I still think that minimal documentation works great...right up until something goes bang outside of the Scrum Team remit because of a change they made and the company has an immediate-high-priority problem. Documentation is the go-to. Commented Aug 13, 2014 at 7:25
  • 2
    the problem is, too many teams focus a lot on producing tons of "Write-Only" documentation that is quickly out of date and no longer useful when you actually it; you really have to make sure they're not just doing it for the sake of meeting some arbitrary quota and that they're actually producing useful documentation, and keeping it up to date. If the documentation is not updated frequently (a huge time sink), then it will have errors. When it has errors, the readers won't trust it... Commented Aug 26, 2014 at 8:17
  • Unit tests on the other hand reduce the bugs you're worried about before they happen and serve as a sort of living documentation that's always up to date and details out every last bit of the system (if you're doing it right). Obviously unit tests don't replace documentation, but rather augment it. -- I assert my opinion that especially in the types of situations you describe: Lots of good solid Unit tests > Lots of Documentation. Commented Aug 26, 2014 at 8:19

2 Answers 2


There can be no general answer to this. Multinational or public companies do vary greatly. Software developed by such companies varies even more in size, type, purpose, usage, life expectancy etc. In general, the bigger, longer used and maintained, more complex the software is, and the more people are involved (at the same time and/or over the long term), and the more regulated the domain is, the more documentation it requires.

The new Scrum Master balked at any documentation

... which sounds a bit overzealous to me. All these people can most likely quote the relevant parts of the Agile Manifesto by heart:

[...] we have come to value: [...] Working software over comprehensive documentation [...]

They often forget to quote this though:

That is, while there is value in the items on the right, we value the items on the left more.

You say

we seem to have settled upon documenting any aspect which has the risk of impacting another departments dependency.

(In short - if they break something that is not theirs, they have some documentation to back up the process, intent and reasoning).

which to me sounds a pragmatic approach, the same as I would follow. There is indeed no value in producing documentation just for the sake of it, but whenever stakeholders request documentation, and/or there is a problem identified stemming from inadequate or out of date documentation, the Scrum team must address it. Of course, face to face conversation is more effective on many levels than written documentation; however, it lasts only as long as participants' memories, and it is not feasible in some cases (e.g. distributed teams). Whenever we need more lasting and/or more transferable traces of things, we need to document them.

The primary rebuttal against in-depth documentation was that

  • It needs factored in as a User Story and given a points value (which I accept)
  • It ruins the flow of the developers work (also accepted)

Well, one may also say that testing ruins the flow of the developers work. As well as lunch breaks ;-P

Note that whatever one is not accustomed to, tends to break the flow indeed. Once we get used to it and gain experience, it will become part of the flow.

  • Documentation is out of date within a week because of code changes/imrpovements etc (which I do not wholly accept)

It is indeed a risk, but it depends entirely on what is documented. Document not the low level details of the code which may change by next week, but the higher level aspects - architecture, design decisions, patterns used, interfaces etc. - which don't tend to change that often and/or are not directly present within the code, but are crucial for e.g. an outsider or a new team member to quickly get an overall picture of the system.

  • Documentation is contained within the code (Which I have rejected outright as worst practice)

Depends on what this means. If this means autogenerating documentation from code comments like Javadoc, it is fine although in my experience mostly of limited use (except for public interfaces). If it means embedding explanatory comments within the code, IMHO it is almost always a Bad Idea (except for rare and limited cases like implementing a specific algorithm, or performance tuning changes). If it means writing readable, self-explanatory, fluent code, I fully agree. IMHO well written, clean code rarely needs any comments.

So, to sum up with a few rules of thumb:

  • Talk to your PO, stakeholders and the Scrum team, to find out who needs what kind of documentation and why (and whether their reason is good enough).
  • (during e.g. reviews and retrospectives) Identify any problems caused by missing or inadequate documentation.
  • If there is a justified need, do the minimum necessary work to fulfill that need. (Taking into account the expected lifetime of the need / artifacts - you may want to optimize for the long term, not the short term. E.g. writing a script to autogenerate a document from config files is obviously costlier than copying it manually once, but if this document needs to be updated every week for the next 5+ years, the script will quickly pay for itself.)
  • Always strive to avoid duplicating info as much as possible. Ideally every piece of information has a single source, so if it needs an update, you can do it once at the source. It may need to be replicated / copied to other places, but strive to solve this via automation instead of manual work.
  • If (and as much as) you produce documentation, strive to make it in the most accessible, easiest to maintain format (unless of course it is confidential). In my experience, this means a wiki like Confluence you mentioned. It can import Word docs, it keeps a history of all changes, and it can even be autoupdated using scripts.
  • Also - as processes and needs change - look for out of date, out of use documentation and if you find such stuff, eliminate it.
  • 2
    Peter, you are quickly fulfilling the role of my personal coach. As I am a very junior PM/Portfolio Support your answers have helped me to greatly focus my intentions. I really appreciate you pulling at the various threads in my questions. Commented Aug 12, 2014 at 21:30
  • @Venture2099, wow, I am honored. Glad to hear you found my answers this useful :-) Commented Aug 12, 2014 at 21:57

Well the answer is really "It depends" mixed with "Why do they need it?" and "What's the least you can get away with?"

This is really about interviewing your stakeholders and doing a 5 Why's type analysis. Find out why they need something, so you can then work to meet that need with the minimum work on your part or even not at all because it doesn't apply.

I used to be the PMO lead for an agile group inside a massive waterfall, Six-Sigma, quality control driven company. We needed to be able to release hardware products to the market often in as little as three months. The mothership took two to three years to release a product. While the main company needed that 2-3 years, we were taking their finished products and putting them into our product so we were using all finished components which we then added software to.

The waterfall/quality process of the main company added months to our projects. Because the quality team could stop us from shipping, we couldn't ignore the process.

I scheduled stakeholder interviews with all organizations we touched. I found out what they needed and why they needed it. By digging into the why, I was often able to see that it really didn't apply to us. It was just a process so entrenched that no one questioned it. I was then able to explain how our projects worked and why we didn't need to meet these requirements.

In the instances where we had to meet some corporate requirement, the why analysis let us see what was the minimum we needed to do in order to satisfy.

Oh and in some cases, the why analysis showed us that much as we thought we were special, we really weren't. Sometimes our team had to suck it up and realize we had to do all that work because it really was needed.

  • Joel - that is a fantastic answer and exceptionally close to my company description. What level of code documentation do external auditors (KPMG, PWC et al) consider sufficient in your experience? Commented Aug 12, 2014 at 20:12
  • 1
    I've been fortunate or unfortunate enough to avoid products that had external audits. I did work with hardware quality groups and they are pretty demanding. However we still pared things down. Instead of using the 30 odd page quality template, we gave them a spreadsheet that answered the questions they really cared about (temperatures under load, drop test results, etc.). Commented Aug 14, 2014 at 15:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.