Part III: Technical Writing Insurgency (Part I | Part II)
“Reading the Jira”
The Atlassian Technical Writers aren’t clairvoyants, neither can we use The Force, but those would be really handy abilities in the documentation profession. The next best thing to supernatural powers of prediction is a technique we call “Reading the Jira”. Similar to reading the future in tea leaves, Tarot cards or the creases in your palm, reading the Jira gives you a sense of things to come and critically, how plans and tasks are changing in the present time. Let me tell you, in an Agile project they’ll be twisting and contorting like some mythical serpent in an old, violent legend.
We basically read every change that’s going on in Atlassian’s issue-tracking program, Jira. As our own software developers are using Jira itself to track their work which we are in turn documenting, by reading all of this Jira material we have a powerful “early-warning” in place, that sometimes makes our prescience seem a little spooky. Milliseconds after a developer updates a spec in Jira, we’re immediately on the instant messenger, asking “How will this affect the documentation?”. Sometimes they’re a little shocked, responding with “Whoa! Easy there!”. This may sound extreme, or perilously close to obsessive behaviour. Still, we’ve persistently found that by tracking the information flow continuously, monitoring changes Jedi style, we win critical days, hours and minutes that we then have up our sleeves to finish the job in time, no matter what’s happened. The flip side of our obsession is that usually, none of the software developers would have thought to inform us about some critical change that turns our priorities upside down. They’re bumbling along, hacking away in their IDE, humming blithely to themselves as the crisis bears down over days and weeks. Rather than a scheduled disaster, “Abracadabra”! We’ve magically got time to finish our work for the release.
At times, reading the Jira is a lot like tapping the stream-of-consciousness from a high-school programming class packed with testosterone-fuelled egomaniacs, but that’s the territory you step into when trying to probe the minds of Top-Gun software developers. Atlassian is most definitely full of those. It’s competitive, intellectually vibrant and subject to tidal forces of opinion.
Authoring in Confluence
Another reason we are able to cope with the dynamic documentation work at Atlassian is due to our product, Confluence (which we also dogfood). Confluence is a Wiki, basically like a web server with pages that anyone can edit. For a Technical Writer, where our communication goal is purely informative, Confluence is a powerful solution. With established pages that we’ve released to the public, we can learn about a problem, find the page, edit the content, have it reviewed and re-publish it to the world in a small number of quick steps. We can have urgent maintenance work on the documentation completed in seconds, when all the pieces fall into place. With the inherent fast-editing capability in Confluence allowing anyone in the company to edit the pages, my subject matter experts are brought much closer to the content. It only takes a few minutes of their time and they can make all necessary changes immediately. This adds obvious bonuses to technical accuracy and speed of review (enabling multiple, iterative reviews to take place). Of course, professional writers are still essential to bring refinement, structure and enterprise standards of communication to the material.
If you’re a Technical Writer about to embark upon an Agile adventure, you’re in for an exciting ride. Throw out the rulebook, publish in a Wiki and get your developers using a quality issue tracker.
Finally, I will leave you with the words of Governor Bibble. Remember: “A disruption in communications can mean only one thing… invasion!”
Ed Dawson is the Technical Writing Team Leader at Atlassian.
This is the final installment in a three part agile technical writing blog series: Agile Technical Writing – Part I | Agile Technical Writing – Part II
Learn more about technical writing and agile development inside Atlassian