End user documentation and definition of done

Last post 04:47 pm December 2, 2012
by Fredrik Vestin
6 replies
09:44 am November 30, 2012

Hi all,

An interesting thing came up on our last retrospective that I'd like your thoughts on.
Our DoD for a story says that functionality needs to be documented in the end-user documentation. We're currently working on an epic that contains multiple stories and the epic spans several sprints. This epic will go into the next release. The developers that write documentation says it's unpractical/waste of time to update the documentation after each story because it will have to be rewritten later as new functionality is added. Instead they want to add a story like "write documentation for feature X" to the backlog. The team acknowledges that this conflicts with our DoD so they asked for advice on how to handle this situation. Observe that for "normal" stories that are not part of epics the team still want to have updated docs as part of DoD and they only want to defer documentation for epics.

What options do you see?
Modify the DoD like "update documentation if it's a story, defer documentation for epics"
Remove documentation altogether from the DoD
Update documentation although it perceived as waste

Have a nice weekend all!

11:27 am November 30, 2012


I'm assuming your epic spans several sprints.

In Scrum, teams deliver a potentially releasable increment each sprint. What happens if, your team has completed 2 stories of the 5 story epic,and your PO decides to release the sprint increment?

12:38 pm November 30, 2012

Why would the documentation need to be rewritten? Smells as if the
functionality is not being written incrementally. If it were, seems the
documentation would be incremental as well.

Let's say it does need to change with each incremental addition (it will),
wouldn't building it once make the next time easier, better? What if they
find the next increment is not needed (as Charles says) and their good to
ship? They can't, because they have undone documentation.

They put Docs in their DoD for a reason... they should stick to it or drop

On Fri, Nov 30, 2012 at 9:44 AM, <ScrumForum@scrum.org> wrote:


12:54 pm November 30, 2012

Excellent points, Ryan.

One other thought occurred to me, as a former developer. I never really liked writing documentation, so I'd much rather bite it off in small chunks.

Also, isn't the same argument true for code? I mean:
1) Don't we have to rewrite/refactor code as the design evolves? I mean, the alternative is to try to get all of the design "right" up front so we (theoretically -- though though the theory never proves true)never have to re-write any code? If you're truly working incrementally and with decent design, very little will need to be 'updated'
2) In the same way that tests are validation for correct system behavior, isn't the end user docs also a sort of validation that is valuable?

And one more thought(I know, I said I only had one, and clearly had more)... The PO must also agree with the DoD -- does the PO like the idea of having incomplete documentation at the end of the sprint?

12:55 pm November 30, 2012

Hi Frederik

It sounds as though the user stories comprising the epic might not be well formed. They should be independent (Google for the INVEST user story criteria if you haven't already done so). That means the user stories should be independent enough to support the Definition of Done, including any requisite documentation.

Also, as Charles says, each end-of-sprint increment should be potentially shippable.

Frankly though, I smell a rat even at this distance. If the developers are correct and documentation would have to be extensively reworked in each sprint, what does that tell you about the stability of the code they are generating? Won't that have to be extensively reworked in each sprint as well, including code comments and unit tests? Otherwise, why would the documentation for it be so inherently unstable? If the documentation changes between sprints are truly considerable, what are the implications of that for architectural stability?

01:49 pm November 30, 2012

"tell you about the stability of the code they are generating"

I'd say it tells us they are in the realm of complexity. As such, getting
to a point of being fully done in the context of their process will help
get them closer to a known world. Scrum at it's best! With this new
knowledge they can provide an updated forecast and use their definition of
done (and brains) to make their past creations sustainable through
refactoring in the context of delivering value.

Win Win!

On Fri, Nov 30, 2012 at 12:55 PM, <ScrumForum@scrum.org> wrote:


04:47 pm December 2, 2012

I'll try to answer all questions and comments in one post:

the epic spans several sprints and the release are a couple of months away, so for this reason the PO would be OK with not having a fully completed end user documentation after each sprint. There's a good split of functionality in the epic so the individual stories add value by themselves but the PO feels that to release we still need 2 more months of stories before release. We've received feedback from end users that confirms this as well. So yes, the functionality is growing in small steps and could basically be released after any sprint but the team thinks rewriting the documentation is waste as new screenshots would need to be added etc after each story etc.