The Bucket, the Whisk, and the Lighter

Posted by admin on April 8th, 2012 filed in Technical Writing

A colleague of mine offered us a short workshop about modern technical writing, nice punchline included:

The target group for the workshop was technical writers and developers. The attendees played the role of the tech writing department (TW), while the presenter played the other roles: development, quality assurance, user interaction, and product manager (DEV, QA, UX, PM).

In the beginning of the workshop, “Development” gave “Tech Writing” three products to document, so we split up into three workgroups. The three “products” were a bucket, a whisk, and a lighter.

The warm-up task for each group was to work out the TOC (table of contents) for their “product” according to our writing guidelines. We didn’t have to write any actual content, just jot down a mock-up outline of tasks and concepts that we would expect to document. As an added learning experience, the non-writers could watch how writers approached their work: For example, for a whisk you could doc concepts such as “beaten egg whites”, for a bucket procedures such as “Transport water”, or for a lighter “Refill lighter fluid”, and all these would be part of larger sets of processes and concepts, etc.

After a few minutes, the presenter collected our fake TOCs, put them up on the projector. The following conversation between him, “PM” (product management), and us, TW (tech writers), ensued:

“PM”: The Project Manager asks how this content will look when you put it together in one book?
TW: What? Why would we put a bucket, a whisk, and a lighter in the same documention?
“PM”: Because it’s the Product Manager’s requirement for this product.
TW: Well, we didn’t know of any such requirement. Aren’t we documenting three products?
“PM”: No, one.
TW: Huh? Then why are we writing about unrelated things such as buckets, whisks, and lighters??
“PM”: Because that’s what Development produced this sprint.
TW: Okaaay? Why did Development do that? Which problem are we trying to solve here??
“PM”: Development was tasked to produce a container to hold a liquid, a source of heat, and something that stirs powders into liquids.
TW: Riiight… What the bleep did the customer order, Product Manager?!?
“PM”: Oh, the customer said something about making coffee. … … :-D

At this point we’re all groaning and rolling our eyes at the presenter, who proceeds without missing a beat: What was the problem? How can we fix it?

The problem was that all teams worked in self-imposed silos, and the Product Manager assigned subtasks without making sure the teams knew which overall problem the customer was trying to solve.

  1. If DEV and QA had known the overall goal (making coffee), they would have interpreted the requirements to produce a cup, a kettle, and a spoon.
  2. If TW had known the overall goal, they would have delivered one book “how to make coffee”, and not three with irrelevant examples for “liquids”, “heat sources”, “egg whites”, and “watering plants”.
  3. And most important of all: The customers would not waste time calling support because the documentation does not answer their questions, and the product does not fulfil the requirements.

In Agile Software Develop, every Task is part of a Story, which is part of an overall Epic, so the implementation teams can always see their tasks in context. This prevents misunderstandings so that DEV, QA, and TW do not spend time on unnecessary details.

Agile User Stories are written after the “As a (role), I want to (perform a task) to achieve (a goal)” template. Keep in mind that not only UX, DEV, and QA benefit from user stories, but also TW must have access to them. The information contained in user stories greatly simplifies the task of drafting user-relevant documentation, even before new functionality is implemented and ready for testing.

Consider that software development is not yet completed with DEV’s last source check-in: After DEV implements a feature, TW still needs time to write help sets, DEV needs time to integrate the help sets into the product, and QA needs time to test the help sets in the build. Having access to Agile User Stories let us use time more efficiently and avoids the situation where TW spends the first half of the sprint waiting for DEV turn-over, and then rushes through the second half to turn over online help to QA in time.

The workshop was a humorous and memorable way to get the message across. Our DEV and QA teams now assign explicit TW tasks for us as part of their Agile Stories. Looking back, DEV, QA, and TW have left their silos and started cooperating beyond their own noses. — We even got positive customer feedback for our new “style” of user-relevant documentation.

Comments are closed.