Why did we abandon AuthorIT?

In this series of blog posts, I'm sharing the huge impact that our switch to Agile development practices has had on our documentation systems. This impact includes (catching my breath) forcing us to give up using AuthorIT to produce our documentation.

If you'd told me two years ago that I'd have written that sentence, my eyes would have gone wide with horror, for our AuthorIT system is mature and powerful, efficiently automating documentation builds and publication, in all its complexity.

Many factors went into the change, so I'll group and tackle them separately:

• Process reasons
• People reasons
• Tool reasons

While process drivers from our development environment would likely not, alone, have forced our tool migration, they were substantial and complex:

New documentation outside of our CMS

A fact that would upset anyone responsible for content management, I found that our newest products and technology were being documented entirely outside of the existing AuthorIT system. All of our years of single-sourcing were being unraveled! Each month that went by, the situation worsened.

• API docs - Our new work centers on a Service-Oriented Architecture (SOA) product, which needs developer-written documentation (now done in Drupal) and an API reference (built manually using Sandcastle). Neither piece could be documented by developers in our current system.
• Configuration docs - Our new user interface is created entirely in .NET web parts,  each of which has its configuration documented in a special HTML file that resides inside of the code package. We had no way to unify this fractured source within our AuthorIT system. 

And not only is the source fractured: users are forced to look in multiple locations for information, which is unacceptable UX. Nor could we single-source this new content for reuse (such as for our training materials). The documentation situation was getting horribly complex and unfriendly.

Process goals unmet by AuthorIT

The other major area of process unhappiness was the ways in which our documentation system failed to participate in the Agile development systems that we crafted for our code:

• Continuous Integration builds - A huge change in our development practice was re-engineering to support continuous integration: it’s no longer good enough to have a feature pass tests on a local build – the code check-in now triggers a “commit” build immediately so everyone can get email notifications if the change breaks the build or any other component. This change speeds up the testing cycle immensely, helping teams finish more stories per sprint. Our challenge was how to set up docs to participate in continuous integration as well, updating all deliverables as soon as source file changes are committed.
• All source files managed in Visual Studio - Beyond continuous integration, we saw that having 100% of source material — across all deliverables — managed, branched, and built inside of Visual Studio (Team Foundation Server) streamlines all processes immensely: it grants one-and-only-one simple way to check out source, associate it with sprint backlog items, and track progress. Everyone in Production is licensed for TFS and can participate in updating documentation stored in TFS, with no change in process. 

Solving that last point brought benefits I didn't anticipate: Having documentation source on equal footing with code source does more to elevate the importance and visibility of documentation than anything else we’d tried.

Next, I'll explain the people issues that drove our migration.

Comments

[Sgreywalker]

Wow, that's shocking news indeed! What are you replacing it with?At my workplace, sourcing everything in a wiki (Confluence) seems to work pretty well in the Scrum methodology here. We usually segregate original developer drafts into their own separate pages corresponding to each story, then mark those pages as "obsolete" once we move their dev-draft info into its final resting place in a particular documentation space. Many of our information consumers use Confluence directly, but we also can publish any specific content from any "space" into a WebHelp output by exporting HTML from Confluence into RoboHelp. (This is a relatively turn-key operation with only one or two text replacement passes before import into RoboHelp and after publishing into WebHelp.) We also deliver some content in FrameMaker-sourced PDFs that are created by copying completed pages from Confluence and manually massaged. (I haven't yet had the opportunity to try and make Confluence's PDF exports be "professional-looking" enough to compete with FrameMaker output.)

The hard parts are dealing with version control in a wiki environment, and the overhead in a Scrum Task Board system to link up dev-drafts, writer-drafts, tech reviews, editorial reviews, and get it all "Done" within a single sprint. We've tried decoupling dev work from doc work, and we've tried staying in lockstep on each story. The big problem staying in lockstep is that stakeholders aren't usually comfortable with seeing "evolutionary documentation" in action. In the early sprints of a release, their impression is that the doc looks too granular and doesn't seem to paint a big picture very well. (As should be expected.)

I've come to realize that traditional doc plans are inherently "waterfall" and trying to develop doc in an agile shop in a way that builds out a doc structure that you know you want to deliver at release is at odds with staying in lockstep and calling doc "done" and "shippable" with each story. It's tough trying to straddle the fence in this regard. Not impossible, but tough.

[Dian Kjærgaard]

Your observations confirm my belief that two types of documentation are necessary for complex applications: the granular type that is fully integrated, what-you-need-when-you-need-it - and the other type that creates big-picture overview(s) for users and, where relevant, system administrators.

Thanks to Tom Johnson for drawing attention to this thread via Twitter. Blows my mind.