[ Draft of the article that CIDM is publishing in the June 2012 edition of Best Practices ]
Now several years into our Agile experiment, I see that habitual, default ways of generating content are not just inefficient: they've become lethal. So much discussion of content management focuses on structuring workflow around published documentation sets, but Agile cranks up the pressure on how we go about dreaming it up from scratch, by and with production team members who never touch the formal CMS.
1. Sprint arguments and artifacts (collaboration imperative)
Our Agile model uses a brisk 2-week iteration cycle, during which new functionality is completely defined, coded, integrated, code-reviewed, tested (manual and automated), and documented. The teeth behind this ideal is our Definition of Done: fail to meet it, and your story cannot be called finished and cannot be demonstrated during the spring review, which we hold as a video conference so that customers, partners, and stakeholders can attend.
Making this even more challenging, our technical writers are shared across teams, so that the second week of a sprint is a frantic whirl of research and writing to get all of the documentation done for all of the teams in time. Like it or not, the reality is that each iteration resembles a mini-waterfall of development, with the first half characterized by approach/design debates and coding trial and error and the second half a buzz of testing and documenting, as the feature solidifies and begins to function.
When all else fails, the default way of communicating about complex features is email: long, difficult threads, often with attachments containing tables, samples, and hastily marked screenshots. The technical writer who finally finds an hour to turn her attention to the debated issue has a miserable task ahead, slogging through these threads and materials to figure out where things stand, what's true. There's just not enough time at the compressed final days of the sprint to process much of this, if documentation is to be written and reviewed by its close.
The imperative? Have those product owners and business analysts create these descriptions, issues, examples, and scenarios in a collaborative context, such as a wiki. That is, rather than have old emails floating around with the earlier, erroneous functional description of an approach, have that be an earlier version of a wiki page, which is there for historical verification only. Let the writer and tester rely on the latest version of such pages to guide them in completing their tasks. Let the wiki notify those involved of changes to the page, and end the nightmare of offline artifacts and authoring-by-email.
2. "Find it? Fix it!" (non-ownership imperative)
Yet another Agile rule we hold to is "Find it? Fix it!", which is a strategy to prevent the accrual of technical debt. Simply put, if you see a bug, jump in and fix it, even if it's not "your" code. And that is where our default behavior with documentation slows us terribly. Here is an example of the ping-pong of effort and communication that we do by default:
- My developer figured out where he was led astray from something not being noted in the docs. He located the topic in the Helpsite, created a new sprint work item, wrote up in the work item what he thought needed to be changed, and emailed me to tell me about the work item.
- I found and checked out the source topic, wrote up the note, described the change in the work item, closed it, and emailed him back.
- He reviewed my work and approved it.
However, if we managed the same topic in a wiki, we could save tremendous energy:
- He locates the problem in the wiki, clicks Edit, and fixes it.
- The wiki emails me his change; I edit and approve it.
No work item creation, no emails. We would still have version control and history tracking safeguards through the wiki mechanisms, but there would be no waiting for the nightly build to verify the doc fix (something that frustrates the teams).
The imperative here is to have all team members be responsible (response-able) for fixing documentation problems that they discover, as they discover them: find it, fix it, and move on. Let the wiki handle queuing the submission and notifying the technical writer to give it an editorial clean-up and approval. Let reporting on these activities reveal where the problems are being found, and let wiki features broadcast and promote these content improvements, all without manual babysitting. Strategically, content strategy needs to increase efficiency relentlessly: Don't let your writers become bottlenecks.
3. Continuous Delivery (dynamic content imperative)
It may sound as if secured wiki technology could solve all of our problems, from streamlining our artifact creation to updating our documentation on-the-fly. But nothing is ever this simple, is it?
We are just now entering a new phase of our Agile implementation that will challenge us profoundly, as we attempt Continuous Delivery. Being able to deploy code and doc updates at will every other week brings an untold level of complexity to our process. Here is a core bit of complexity, around how we document the new features that roll out continuously:
- Every story that we complete must have a Development Review Note written for it (currently, we write this in a Drupal page).
- A story might be pulled from a sprint review at the last minute (for failure to finish sprint tasks, or discovery of a bug).
- A story might be appropriate for internal sprint review only.
- A story might relate to our old product, our new product, both, or neither.
- A story might be part of a larger, incomplete sprint epic (large chunk of functionality, for which the feature is being held until complete).
- A story might need to be shown to customers in a sprint review yet not be ready for immediate deployment (being part of an incomplete epic).
- A story might have no impact on customer configurations, or it might be a critical change.
- Each sprint the product might be deployed to customers, or the deployment will be postponed another sprint.
Head hurt like mine? So, the speed and dynamism of these small chunks of documentation — these sprint review feature summaries that need to be assembled into regular deliverables on demand — argue for authoring and tagging these chunks with extensive metadata, and for publishing these chunks with queries that handle the complex filtering needed to give each audience member what she needs, when she needs it. Under Continuous Delivery, this information will be critical throughout and beyond the organization, for determining the actual state of the product at this moment.
Nearly any database will do, if the alternative is to do without. For our first implementation, we are extending our team environment in which we create and track our sprint stories (product backlog items): Team Foundation Server on Visual Studio. We are developing a unique type of sprint work item that will be associated with every story, which will manage this release content. It will have fields to track all of the metadata implied in the bullets above, and it will have a rich text field for the content itself. We will create TFS queries to extract the latest information to meet review and stakeholder needs, and we will embed the content in our various websites.
If this quick approach proves insufficient for continuous delivery needs, we go back to the drawing board. As with all of our Agile commitments, we keep changing the tools and the process until it works. With Agile, the only thing we can be sure of is that things won't return to the way they used to be.
