Agile software development at Atlassian
Part I: Technical Writing in Space (Part II | Part III)
The Problem
When you first begin Technical Writing in an Agile development environment, you face a number of immediate problems. The first is that you seemingly have far less time to do your work. With the developers choosing accessible goals and shipping them regularly, as a writer you feel that you’re rushing. Sprinting (if you will), to use the Agile nomenclature. It’s like stepping into a near-vertical mountain stream during the spring melt. It’s bracing, turbulent, and full of razor-edged boulders.

Each milestone contains a number of user stories (and their component parts, story points) which the developers are churning out like mincemeat. If you don’t catch the respective developers while they’re working on these little pieces, they’ve moved on and can often be quite disinclined to shift their focus to the ancient past of last week.

I’d argue that one part of the problem is that Agile philosophies are essentially hostile to all non-programming parts of the delivery process. Where you once had Analysis, Design, Implementation, Testing and Documentation, you now have Planning Poker and Implementation Sprints. Analysis and Design have been savagely pruned. Testing (in its traditional Release Testing form) has been all but eliminated, due to Agile’s reliance on integrated unit testing and peer review. Finally, the feeble proponents of Documentation, (always outsiders in the world of development) are easily shunted out the door by a philosophy so savage it has devoured parts of itself in order to become leaner.

Many a Tech Writer’s response to Agile Development gives me flashbacks to Star Wars Episode 1: The Phantom Menace, specifically a character called Governor Bibble. A learned, middle-aged fellow, he was Queen Amidala’s faithful council advisor. Bibble remains in the Imperial Palace during a full-scale invasion – while the Queen escapes to the forest to make battle plans. The rules of his world have just been turned upside-down.

Soon, the fearsome agents of the Trade Federation arrive, flanked by their terrible battle-droids. Bibble waits in the Imperial Court, still hoping for reason to prevail.

A Technical Writer’s protestations against the Agile process usually run something like this:

  • Agile Nute Gunray (riding in a fearsome mechanical chair): “When are you going to give up this pointless strike? Your Queen is lost, your people are starving, and you, Governor, are going to die, much sooner than your people, I’m afraid.”
  • Governor Bibble, Technical Writer: “We’re a democracy! The people have decided… they will not live under your tyranny!”
  • Agile Nute Gunray: “Take him… away!” (Waves his arm dismissively. Droids march Bibble off to prison.)

The key with Agile Documentation is not to become Governor Bibble, but rather be more like the Queen. There is value in trying to secure sanity agreements on minimum levels of documentation and sensible time frames, but be prepared for documentation to be bundled as a “concurrent activity” (this seems to be something of an occupational hazard in Technical Writing). The time you spend senselessly complaining and arguing your case could likely be better used by acting decisively and switching to an insurgent strategy (which I discuss in Part III of this series). Waste no time – embrace the chaos!

Ed Dawson is Technical Writing Team Leader at Atlassian.

In Part II, Planning for Agile Documentation, we’ll cover the puzzle of estimating Agile projects, the virtues of dog food and the Programmer’s Wild West Saloon.

This is the first installment in a three part agile technical writing blog series: Agile Technical Writing – Part II | Agile Technical Writing – Part III

Technical Writing In Agile Software Development – Part 1