Acceptance Criteria for Technical Documentation

Last post 09:46 am February 28, 2015
by Jaime López López
9 replies
09:54 am December 11, 2014

I manage an information development team that is responsible for technical documentation across multiple products. One challenge we are having is creating good acceptance criteria for our documentation specific stories. They invariably take the form of:

GIVEN I don't know how to use feature X
WHEN I read the documentation
THEN I know how to use the feature

This strikes everyone on the team as a pretty poor acceptance criteria, but we are struggling with a better way to indicate that a piece of documentation delivers business value to a customer. Has anyone ever applied Acceptance Criteria to documentation? Did you have this struggle, and if so, how did you overcome it?

10:27 am December 11, 2014

Does the release of relevant technical documentation coincide with associated releases of the product?

In other words, does each product release include adequate and relevant technical documentation...or are the product and documentation releases essentially unsynchronized with each other?

06:42 pm December 11, 2014

As an ex qa test engineer who reviewed number of documentation, I would suggest to add things like:
- the documentation is reviewed/approved by the development team

I saw lots of documentation where it was a copy paste of previously (similar) released documentation with no changes. I saw a documentation with examples which were not valid or outdated. We used to have a practice to have somebody who never used a product to go step by step using the documentation and see how consistent it is, how useful it is.
Another point for any documentation is a doc has to have only what it should have with no info duplication. A doc which is too long, too detailed is not always a good doc.

02:49 pm December 17, 2014

Ships at the same time as the product.

01:55 am December 18, 2014

Since it ships at the same time as the product, add feature documented to your Definition of Done.

Personally, I can't see documentation as a separate story. Either in DoD or as part of a deployment checklist.

03:11 am December 18, 2014

> Ships at the same time as the product.

Then include documentation in the Definition of Done as Robert says. The DoD should assert the qualities for "potentially shippable".

The Development Team may plan tasks into the Sprint Backlog for producing appropriate documentation. Note that the team must include all of the skills, including technical authorship, for producing increments that satisfy the DoD and are release-ready.

06:00 am February 27, 2015

I have a question regarding the inclusion of documentation in the DoD of the Dev Team.

It is supposed that the Sprint Retrospective event is used to make improvements for next Sprints but these improvements has to be an agreement of all the Scrum Team. So, can Dev Team reject the inclusión of the documentation in the DoD? If the answer is Yes, does documentation has to be included as a requirement and the PO has to create the PBI's?

02:41 pm February 27, 2015

> can Dev Team reject the inclusión of the documentation in the DoD?

Yes. If they are unable to create documentation then they will be unable to create increments that feature it. Therefore it could not be included in a usable DoD.

> If the answer is Yes, does documentation has
> to be included as a requirement and the PO
> has to create the PBI's?

No, because even if this requirement is included as PBIs, the Development Team will still not be in a position to induct the work into their Sprint Backlog and deliver it.

The PO would be better off finding a team which actually does have the ability to deliver increments of an appropriate quality, including any necessary documentation, as per a suitable DoD.

07:39 pm February 27, 2015

NB in a situation like this, I'd suggest that the Scrum Master investigates why the production of documentation is seemingly contentious.

09:46 am February 28, 2015

But, my scrum understanding, if the PO consider that documentation is the expected increment of the sprint, why have Dev Team be changed for a better one?