Agile. The philosophy has influenced IT development since the 90s, but it still strikes fear into the hearts of writers with a raft of terms and fundamental processes that conjure up some terrifying possibilities. Agile can sound chaotic and hostile to a writer.
- Scrum: The word just drips with testosterone-charged action, of beefy, sweaty team members locked together and heaving against the opposition. Where does the writer fit in? Am I the ball that’s stomped and kicked into the turf?
- Lean: No specifications? I have to rely on daily stand-up meetings, face-to-face conversation, email threads, task boards, and the issue tracking system? And I have to use these sources to write doc for product I most likely can’t see or use?
- Sprint: I’m pushing along in the scrum, racing to produce shippable doc every two to four weeks? Without specs? Or a product? While participating in a daily meeting for every scrum?
Even the Agile Manifesto seems to aim a stake straight at the writer’s heart in its core values: “we have come to value working software over comprehensive documentation”.
When reading about user documentation in Agile, I’ve noticed that most commentators focus their discussion on assuaging writers’ fears. They suggest processes and techniques for writers to stay sane and productive in the face of chaos, and maybe even to thrive and be happy. I think happy writers are a good thing. However, as I mentioned in a previous column, happy, productive writers do not guarantee user success. I was once a writer happily producing thousands of pages for frustrated users who propped up their monitors with my manuals.
I’ve worked in a hybrid Agile environment for about six years now. I’m still (mostly) sane. Feedback from coworkers and customers indicates that I’m still productive. I can say without reservation or qualification that I’m happy. Why am I happy? I’ve experienced some of the writer-friendly aspects of Agile, developed some coping strategies for the not-so-friendly aspects, and I’ve seen some of the benefits that Agile can bring to the user. I think that Agile helps me be a better users’ advocate.
Writers in Agile
Agile is fast, but several practicalities mitigate the breakneck pace for me.
The Little Things
Agile methodologies emphasize continuous iteration in small units of work. The units of work represent very specific user goals. In Scrum, the smallest unit of deliverable work is called a user story.
Years of painful pre-Agile lessons taught me to write for reuse, and Agile’s fast-paced, iterative nature punishes custom, ad hoc writing. Topic-based authoring is a natural solution. Stories map nearly one-to-one to topics. Each topic captures a unit of work sufficiently as stand-alone content for presentation to stakeholders and for release notes. When it comes time to integrate the new content, I’ve worked hard to ensure that the overall doc project is flexible and extensible enough to accommodate the new topic with minimal effort to update and enhance longer-form documentation.
The Big Things
Speaking of longer-form docs, Agile methodologies may focus on atomic-level units of work, but they also acknowledge the need for larger, big-picture goals and deliverables. For example, Scrum extends the narrative metaphor and collects related stories into epics. I can always negotiate enough time and resources for larger documentation projects in an epic.
Priorities
Because of the constant churn of quick iterations, my to-do list is always full to bursting. As a defense, I perform doc triage on a regular basis. Every deliverable doesn’t require the same level of effort and overhead. For example, a user story and its doc doesn’t always represent a complete and independent feature for customer delivery. The end user can be an internal stakeholder, which means I can still meet requirements with lower demands for production, integration, and delivery (and lower stress).
Less Waste
In previous development regimes, I could toil for six months on a product or feature that never saw the light of day. If a deliverable isn’t ready for release, it just gets bumped to the next cycle for the next release. With the release cycle so short, the delay is seldom tragic. My doc content follows right along, staying relevant and fresh both in the product and in my own head. Experience has taught me that I’ll see the feature again soon.
Benefits for Users
I’ve highlighted some of the features of Agile and my reaction to them as a writer, but what about the user? What, if anything, does the user get out of Agile?
Fresh Content
Agile timelines with their frequent iterations ensure that the content for an active project is no older than its development cycle. Users get access to updated content every two to six weeks. In addition, when I receive mid-stream feedback or non-critical doc bugs, the doc update is already in the plan. There is no drama.
Better Content
Agile can also improve the quality of these frequent updates.
As a visible member of several scrums, I’m constantly talking with developers and product owners. The answer to 90% of my questions is a short conversation or a short stand-up meeting away. My coworkers don’t have a stale, old spec to hide behind. They don’t feel like they need to hide from me because our interactions are quick and painless. I also don’t have a stale, old spec to cling to and give me a false sense of security. I spend much less time answering questions like “Where did you get this? This is completely wrong/old/obsolete!” Although I felt justified in the past when I answered “from the spec”, I got no satisfaction from it. It wasn’t productive. I’d rather not generate bad blood and burn goodwill. I’d rather the doc be correct.
Apart from simple mechanical correctness, some of the best ideas for doc enhancements have come from developers, account managers, and support personnel. In the end, my users benefit from richer content.
User Input
To quote another item from the Agile Manifesto: “we have come to value customer collaboration over contract negotiation.” In theory, customers have a formal and active role in development. In practice, the level of involvement can vary based on several factors, not the least how open they are to collaboration and how capable they are. When I have a friendly, motivated customer, I experience Agile at its most satisfying. I get constructive and innovative feedback from the customer as I’m writing the doc, and I know that all my users will benefit from the customer experience baked into the doc.
Agile is not a silver bullet. It’s also not a monster that marginalizes and devours hapless writers. It’s simply a development methodology with its own set of challenges and benefits. I’ve come to interpret the Agile Manifesto’s valuation of “working software” over “comprehensive documentation” not as a threat but as an enjoinder. The goal of product development is not to write detailed specifications and fat reference guides, but to deliver a product that enables user success. Documentation still plays a key role is keeping the user happy and successful.
Overall, my time in Agile has led me to my own simple tweak of the Manifesto: “I have come to value working documentation over comprehensive documentation.”
