I remember when software documentation was linear and waterfall. No, really.
Those were the days. Software was architected, designed, coded, the code was frozen… (I can totally hear you laughing from there. Shhhhh), and then it was documented. You’d buy disks, in boxes, with actual books included. Printed. On paper.
…and then we had to spend our lunch breaks running from dinosaurs. Ah, the good old days.
Then along came the hyperlink. (yes, that’s what we called it when such things were shiny and new and disruptive. Quit laughing. Shhh.) And everything changed, and technical writers and editors sat around and talked about how this was going to alter our processes. But books were never going to stop being shipped with software, so it probably was just a niche thing.
You can stop laughing at any point. I’ll wait.
.
.
.
done? Good. Where was I? Oh yeah. Software documentation on paper.
We all know that the world has gone through a few major upheavals since then, and one of the most glorious is the embracing of Agile methodology. Not just because, well, Agile, but because to be totally honest, software has always been like that; it’s just that before, when code froze and unfroze and changed and refroze, those freezes were not unlike what’s happening to the permafrost now, which is to say, a sort of very thaw-ish kind of freeze. Which is to say, not a freeze at all. It’s just that back then, documentation teams pulled all-nighters at the end of a ship cycle to document things to make it appear as if we’d always planned the software to be like it was at the time it’s shipped.
My profession was complicit in this unfrozen freezing for a long time, and for writing documentation that made it appear as if software and documentation were some kind of united front. I don’t think that, ultimately, we did anyone any favors in behaving that way. It’s a relief to have moved along from that place.
The first time I saw the phrase “as-built documentation” I may have cried quiet tears of joy.
One of the great things about writing and editing documentation at AlienVault is that the teams have entirely embraced this methodology. And while there are plenty of different ways to approach the mechanisms of producing “docs like code,” here we’re using Bitbucket (through Sourcetree) as a repository, and using MadCap Flare to generate HTML and PDF docs for consumption.
And oh happy day, we are finally, wholly, collaborative. No more of the “I’m in the doc and you have to wait until I’m done if you want to work on it.” No more of the “Hello. My name is Reviewer. You overwrote my changes. Prepare to die.” We can build the docs together, at roughly the speed in which the software is being coded, without having to wait around for the (wholly mythical, in my experience) code freeze before we begin.
The benefits for technical editing, specifically, are phenomenal. When my writers finish working on a ticket (Did I mention Jira yet? I’m so happy to be working in a ticketing system instead of in the oubliette of my inbox), I can look at what they wrote directly in the Bitbucket repository, and I only need to edit what they changed, not the entire document each time.
What this means is that, ultimately, we’re able to create documentation that’s more accurate, that matches what you see in the software, that allows you to find the answers to the questions you’re asking, no matter how much the code changes. We’re able to have complete documentation available for you at launch, and we’re able to adjust for revision in a scant fraction of the time that revision cycle would have taken in the past.
It’s a glorious time for writers, for editors, but most importantly, for the users, and I’m proud to be working in it.
