Part II: Planning for Agile Documentation (Part I | Part III)
On Velocity
When a Technical Writer tries to resist the Agile process, the time you spend senselessly complaining and arguing your case could be better used acting decisively. In Part I, I discussed the dangers of resisting The Agile Way. Like surviving in a tropical jungle, to an extent you must give yourself over to the environment, rather than trying to fight it. This is not to say that there isn’t a number of genuine Agile syndromes that make writers nervous.
One problem that you will see very early on is the issue of estimating work accurately in Agile projects. The difficult element is that user stories of equal size don’t have equal documentation requirements. Remember, all the story-point estimation is being done more or less for the benefit of the hero in the Agile Universe, the software programmer. Some stories are reliably small, with small-ish documentation requirements (which is nice). Of course the converse is also true – some of them have an enormous communication payload (with a deceptively small story point count). Estimating stories and documentation impact is troublesome because as any Technical Writer will tell you, it really depends on the final polish of the feature. Thoroughly buffed and polished features generally require the least documentation. On the other hand, those raw prototypes and brand-new, first-generation solutions are the ones that really need a lot of supporting words.
In my experience, the Agile process largely delivers features on the “raw” side of the equation – this leads me to a rather controversial statement: Agile Requires More Documentation (weather permitting). You may have a magical Agile team that delivers you wonderfully polished, iPod-like features, where you can say “Simply choose your music with the intuitive Click-Wheel!”, but I’d personally expect that to be the exception rather than the norm.
Only once it is possible to lay eyes on a feature and see it demonstrated can the writer truly start to gauge the likely magnitude of the blocks of work. This is where the Agile term ‘velocity’ really takes on a life of its own. With Agile, these blocks come hurtling down the chute at a hundred miles an hour, rapid fire, in random order, ricocheting all over your work schedule. The day after the last sprint, the product is released to customers (with coding probably continuing throughout the day before). Naturally, this creates the need for an occasional ‘tap-dance’ to get the work done in time. As a Technical Writer, it sometimes seems as if the developers are all wielding pistols in some kind of Programmer’s Wild West Saloon, chanting “Dance! Dance! Dance!” as their muzzles spew forth a fusillade of innovation and inspired code.
I paint a stressful picture, but Agile Tech Writing is also a positive experience in many ways. At Atlassian, we are nearly always writing documentation for 100% complete, brand new features. This is a wonderful contrast to some waterfall environments where you spend months trying to write instructions for vapourware, from vague business planning documents and specifications. Generally, Agile also delivers a fresh stream of new innovations which is a great alternative to tired re-hashes of an elderly feature set.
If this were a company that made mediocre products, the “dog-fooding” experience (where you must personally use the products that you make) would be torturous. Yet, because this is Atlassian, the very products we’re dogfooding play a key part in sustaining our sanity.
Ed Dawson is the Technical Writing Team Leader at Atlassian.
In Part III, Technical Writing Insurgency, we’ll cover the business advantages of being a clairvoyant, how to read a programmer’s mind and leveraging Jira and Confluence for documentation.
This is part two of a three part agile technical writing blog series: Agile Technical Writing – Part I | Agile Technical Writing – Part III
Read more about Atlassian’s approach to agile software development