End user documentation and definition of done

Fredrik,

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?

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
it.

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

>

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?

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?

"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:

>

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.

As a tech writer, I would repeat that, in an agile team, the documentation should be treated in exactly the same way as code; that is, rewriting must happen throughout evolution based on the state the content is actually in, you should have potentially shippable code and docs all the time in case you don't get to the end (both code and docs), and so on. 

That said, can I comment on a couple of your specific items? 

1. End Users are often happy not to get the docs in the first instance, but they will not be so happy about it if they end up with poorer quality documentation because the writers (whoever they are) had to rush it at the last minute when they were bug fixing the code (that time 'saved for documentation' at the end always finds another use!), or because the functionality was simply not as fresh in the writer's minds as when they wrote it. 

2. Are you sure you need enough screen shots to take that much effort? IMHO screen shots are often not very useful, and can sometimes be misleading. It's always worth checking they are useful to your readers in all cases (sometimes they are added to make docs look longer and more interesting). Are there ways to get your screen shots to require less regular updates? For example, do they need to show the whole screen (meaning any change impacts on them) or could they just show the bit of the screen you are interested in? If you want to locate the particular bit on the page, could you do this with a line drawing...?

There are several individuals posted interested questions that will answer your question. 

What happens if, your team has completed 2 stories of the 5 story epic,and your PO decides to release the sprint increment?

Also, isn't the same argument true for code? I mean: 

1) Don't we have to rewrite/refactor code as the design evolves? .... If you're truly working incrementally and with decent design, very little will need to be 'updated' -  Charles Bradley

Excellent Point: Should you not provide AS MUCH documentation as needed to make those user stories complete as per the DOD? 

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? - Ryan Cromwell

Exactly: The very fact of trying to document will expose any inconsistencies or design flaws earlier than later. Also the future stories would usually add/update the document rather than rewrite. The word re-write is a negative term and means the team is not mature enough to develop well thought out well refined user stories to begin with.Other wise why would they think of re-writing instead of updating  and adding more the the already good to go documentation?

In general, work like documentation depends a lot on the transaction cost and holding cost. If the changes are incremental and not something like rewrite, the transaction cost will be relatively low. So you may want to document as part of DoD of a story.

However when there are lots of changes around, transaction cost will be relatively high. At that point of time, you may want to document when functionality is relatively stable and batch couple more when you document them.

so as I understood the best practice is to do the documentation as part of the sprint. Considering that can someone share a typical 2 week sprint breakdown. So clearly 8 hours x 10  days = 80 development hours is not possible. There will be meetings, R&D and testing. Question is that from the first days QA and documentation guys cant do much till there is some developed functionality for them to test and document. And if there is development going on on the 10th day (should that happen) when do we test and document that? next sprint? 

Muhammad, under your scenario, perhaps it would be unwise of the Development Team to still be developing on the last day of the sprint?

Keep in mind that Scrum does not waver on the goal of every Sprint to deliver potentially-releasable working product that meets the Definition of Done, regardless of how large or small such working product is.

Echoing @Timothy Baffa's comment, might it be beneficial if the Development Team planned to have everything needed in order to deliver a potentially releasable increment completed by the end of the Sprint?  If testing and documentation is something the team considers required, then they should be forecasting the work for the Sprint to have those accomplished.  The Definition of Done should include testing and documentation and all the work that the cross functional Development Team does is guided by the Definition of Done.