Saturday, December 17, 2011

The role of a tech writer on an agile team

There is a common myth surrounding the agile community that being agile means no documentation. This is a huge fallacy. The agile manifesto states clearly that we value working software over comprehensive documentation. It also states the following:

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

For me as long as the documentation is useful and will be read we should still do it. This might be user manuals or supporting sales material. Whatever the document it's often a good idea to have a technical writer on the team. Some clients do require  comprehensive documentation even if it's just a checklist item. If they can't be dissuaded and they are willing to pay for it then I say do it. So yes we do want a writer on the team.

One mistake I've seen teams make is to start the documentation for a story after it's been completely developed. The theory is that this prevents rework, but the side effect is that there's often documentation left undone at the end of the sprint. The tech writer gets frustrated due to the lack of time left and can feel that it's their fault that the sprint commitments weren't met. This can lead to the documentation to be written one sprint behind the development. What's the big deal with that? Well if there are any questions for the developers they're already focusing on something new. These questions can disrupt the developer through causing them to dredge up the memory or go back to the code to remember what they did.

So how do we fix this? One way is to have the tech writer attend all of the important design meetings with the developers and testers. They should get enough information to start work. Sure there maybe some rework and screenshots that need to be taken can't always be done until the end, but you've now lessened your risk for not getting everything done. If the writer has any questions they can ask the developers while everything is fresh in their mind. Another strategy is to pair the writer with a tester on the team. Testers are great at seeing all of the intricacies of the story and can communicate that to the writer.

I'm interested to hear about how other teams deal with technical writers on their team. 

1 comment:

  1. Hi James. I always thought that the "documentation" referenced in the Agile Manifesto is internal product specifications, not end user documentation that technical writers produce. The idea being not to be handcuffed to a product spec during software development because events "on the ground," as it were, quickly invalidate a static spec written long before development began.

    ReplyDelete