Shannon Greywalker's Blog

Today I was at a local STC networking lunch and was pleased to see how many of us tech writers present were working in Scrum environments. Even better, everyone I talked to was an embedded writer on their teams instead of being a support writer for several teams, as I know some companies try to do with their tech writers.

One person who had read a lot about Scrum but hadn’t yet worked in a Scrum environment asked some questions that I think all of us have asked before we got involved with Scrum (paraphrasing): “How do you write documentation when you can’t see the whole picture until many sprints have passed? Each story is such a small unit of functionality… How do you plan your user guides? How do you write procedures that use several features in sequence?”

The answer is incredibly simple. In a Scrum environment you develop your user assistance (documentation, in-product information support, training materials, etc.) the same way that the teams build the product features themselves: in an evolutionary manner. Just as the developers have to stop thinking in terms of writing monolithic design specs for a release and then trying to develop the features as described in the specs, we tech writers have to stop thinking in terms of monolithic user/task analysis and documentation plans that we then use as a blueprint for developing our product documentation.

Instead, every aspect of the product is developed in an evolutionary manner, iteration by iteration. In sprint 001 you deliver a few stories. Some of those stories will create new functionality in the product and there might be a few topics you author to explain that new/changed functionality. There’s not much in the way of “glue” topics that you can draft at this point: just some basic procedures, reference, and (maybe) some concepts and principles to describe the atomic bits of functionality that your team developed during the sprint. If you’re building some completely new product, there’s nothing that looks like a typical user guide yet. Just a miscellaneous handful of topics in a quick and dirty user guide “shell” just so you have a way to publish the documentation you’ve created so far if you were to hypothetically sell a new release based on what all the production teams have built so far. Remember, one aspect of Scrum and agile methodologies in general is that at the end of every sprint (iteration), you should ideally have a releasable product. So some kind of publishable “user guide” at the end of every sprint is essential. Granted, you typically don’t produce a formal beta or gold release without doing some “hardening sprints” that involve a lot of acceptance testing and bug fixes, but the point is that you should generally have a new product version at the end of every sprint that is nominally ready to ship at least as working alpha code that passes unit, component, and system tests (which can all be automated as part of your continuous integration process).

So in sprints 002 and 003, etc. you are delivering more stories and their attendant atomic documentation topics. At some point, you realize that enough of a big picture is emerging that you can start filling in some of the conceptual and procedural blanks. Maybe you even start writting and submitting user stories to capture some of the meta procedures that require navigating through several features of the product. Or your product owners or other team members start seeing the big picture that is emerging for the release and submitting such user stories to ensure this typical “glue” information is authored.

The point is that as you near midpoint of iterations for a release, the big picture starts emerging and you start revising and enhancing topics that you (or another writer) had drafted earlier in the release. Your topics begin to evolve, just as the product features themselves evolve as one story is delivered, then another story is delivered that enhances/changes the feature originally built in the first story. Just as the developers do not need a monolithic design spec to guide their work, the tech writers don’t need a monolitic documentation plan to guide their work either. You won’t know at the start of a release what shape your final documentation set will take. And that’s perfectly okay. In fact, it’s better than okay because it reflects the reality of large, complex software development projects.

The beauty of Scrum, when it’s done right, is that every story you work on is delivering new user value. It’s perfectly fine if you end up redoing a feature that you originally built two sprints earlier, because you wouldn’t be doing the rework unless somebody convinced the product owner that doing so would add enough additional user value to the release. Likewise for the documentation: if you get to a certain point in the release where it becomes obvious that spending some time to glue together all the topics developed so far will add user value then the user stories to state that fact will write themselves and you won’t have too much trouble convincing the product owner to ensure that some teams pull those user stories and create those glue topics. In other words, you don’t have to “sneak in” the high-level documentation work or spend overtime getting it done. You should be able to convince the product owner of the value of doing that high-level documentation work in some of the later sprints in the release.

And if you can’t convince your product owner? Then don’t do the high-level documentation work. Let Scrum work for you and let failure (on the documentation level) be the impetus for changing tactics in future releases. Let the product be released with a user guide that is less than optimal in terms of top-down flow, reader access, and glue topics, etc. If it turns out that user documentation with rough edges is truly a problem for your customers (and therefore ultimately your sales people), then customer feedback (or feedback from internal stakeholders) will reflect that fact. Eventually feedback like this will convince the product owners to give due consideration to the “doc hardening” user stories that you suggest in future releases.

And who knows? You might be surprised at how many rough edges your users will tolerate. Many of us writers have been trained to strive for perfection in our documentation, but if we’re honest, a lot of the effort we put in to finely polish our documentation (and hopefully win STC competitions) might be better spent elsewhere. What if you can crank out a larger amount of useful information by focusing less on aspects of “polish”? Ultimately, what’s of more value to your users?