Tech Docs as Agile Deliverables

By John Collins

"The big software release is only six weeks away, and we still have 12 weeks of work before we can ship the online help system," your colleague says. "We've got to talk to the project manager."

This scenario may be all too familiar, but does it need to be? Do you need to talk to the project manager? The answer to both might be no.

If you think about it, the software is probably bigger and more complex than your help system. So why would you need six more weeks to finish the help system than the developers need to finish the software? "That's easy," you say. "The team has far more developers than technical writers, and some of the features were just finished in the software—or still aren't built yet."

Those things may be true, but you can probably deliver something in six weeks, to match the software release. Simply put, you can apply the same Agile principles to your documentation as your software development team applies to its work.

Now is a good time for disclaimers.

You may be in a regulated industry with specific requirements on technical documentation. You may not have as much leeway.
This article is written with digital deliverables in mind. Physical deliverables become more complicated.
As with just about any article or blog post related to technical communication, your mileage might vary.

What Is Agile?

Agile software development can take many forms, from the common Scrum to Extreme Programming to Kanban and a number of other methods. At its core, Agile is iterative and flexible, changing when needed and geared toward action.

Technical writers may be most familiar with Scrum, so let's focus on that. In Scrum methodology, there are three roles on the team:

Product Owner: Drives the vision and requirements and makes the final decision when big questions arise.
Scrum Master: Facilitates, clears blockers, protects team members' time, and helps to implement the team's agreed-upon process.
Team Member: Works in some capacity on the project. Includes developers, quality assurance analysts, technical writers, and so on.

Often there's a backlog of features to be built and bugs to be fixed. Everyone expects additional features and refinements to come in future releases.

The goal is to finish each sprint with working software. To some teams, that means releasing code to customers. To other teams, it means that a new feature is finished and none of the code is broken at the end of the sprint, even if a complete release isn't quite ready to ship.

The beauty of Agile is that fully functioning software is released regularly, yet additional features are added over time as scope allows and user feedback comes in. When done properly, users get more usable software from an Agile process than something that's defined, developed, and released all in one isolated chunk of time.

Oh, and that pesky line in the Agile Manifesto about valuing working software over comprehensive documentation? Don't get defensive about "comprehensive documentation." Instead, understand that "comprehensive documentation" in the context of working software has more to do with design documentation like specifications and requirements than the user documentation you write. But also realize that this frees you up to deliver useful documentation instead of comprehensive documentation.

What Would Agile Tech Docs Look Like?

Like Agile software, Agile technical documents are frequently updated and enhanced. They are no longer monolithic piles of information, but rather evolving, ever-improving, integral parts of your product.

In fact, try thinking of your documentation deliverables as if they are software themselves and approach your work as if you were a software developer. If you're working in single-sourced XML or HTML-based content, it basically is software.

Define the absolute minimum that your deliverables need, both in terms of content and form (as online help or as PDF). Then prioritize for the backlog what improvements should follow. The backlogged priorities can then work their way into future sprints.

Let's look at some examples of Agile documentation in two sprints.

Sprint 0	Sprint 1
Write instructions for quick-start guide and release a plain, unbranded PDF	Add branding to output and release a completely branded PDF quick-start guide
Outline the structure for new document	Complete the first draft of the new document
Release fully-finished quick-start guide	Release a basic user guide
Release the English help system	Release the localized help system in top two user languages
Add Feature X topic to user guide and help system	Add Feature Y topic to user guide and help system
Migrate Word documents to single-sourcing tool	Refine single-sourced content and output types for initial draft outputs
Release help system	Release PDF user guide
Add indexing and keywords to help system	Add relationship tables to help system

Why Should I Do This?

My background is in book publishing and print journalism. While we had regular production cycles at the newspaper where I worked, it was still more of a linear "waterfall" process. The move to Agile when I changed careers involved quite a learning curve.

If you struggle with thinking in a waterfall way, you may find yourself at odds with everything else that's going on in your organization. Do you struggle with paralyzing perfectionism? I did. Moving your technical documentation approach to be more like the Agile methodology will bring you in line with your project management and developer colleagues who are all Agile all the time. You'll find yourself able to embrace sprints as a chance to fix mistakes and constantly improve instead of waiting until your work is perfect and ready for the masses.

But more importantly, working with Agile technical documentation lets you manage scope, know what you're trying to accomplish, and focus on priorities. You gain the mechanism to concentrate on what your users really need. For example, instead of shipping no document or shipping a document that's a catalog of every interface element, you can ship a basic task-based document. Perfect form can come later.

Feeling unappreciated as a technical writer? Maybe stuck in a rut describing every screen in your product and producing thousands of words that you doubt anyone reads? Move your documentation to an Agile approach to focus on higher priorities and produce high-value deliverables. As a result, you'll gain relevance and prove your value to your organization.

How Do I Do This?

Here are some tips about how to make your tech docs more Agile.

Find a Product Owner

To adopt an Agile documentation approach, you'll need to be a champion for change. But you'll also need someone who can help you pull it off. Find someone to be the product owner for the technical documents. Hopefully that's the actual product owner of the software team you're on. If that's not possible, find someone else like a project manager or the technical writing manager who can drive the requirements for the Agile docs and build and manage a backlog of documentation features and bugs.

If the technical documents product owner is not also the software product owner, the people in those two roles need to make sure that they agree on the technical documentation approach.

Get Control of Your Releases

As long as you're dependent on others to distribute your digital deliverables, you're going to lose the beauty of iterative improvements to your work. If another team uploads your PDFs to the knowledge base or if product rollouts are required to update PDFs or help systems, then you're at the mercy of those teams.

If needed, work with your developers—and system administrators—to get the infrastructure and access you need to put your technical document deliverables directly on the Internet.

If you control your releases, you'll want to have some process set up around release management. Again, model what you do after what software developers do.

What might be part of your release management process?

Rollout Plan: What steps need to happen to put your deliverables online?
Version or Release Numbering: I like my deliverables to show a version number. It's an easy way to know what you're looking at. Otherwise, you may have to search for that one sentence you rewrote or the screenshot that you updated to know if you're looking at the current version. Maybe you use the versioning number of the software, but maybe you want something more specific to your deliverable.
List of Current Releases: If you manage multiple deliverables, keep a list that shows each deliverable, the release number, the date released, and some notes about the deliverable, if desired.
List of Past Releases: Keep a running page with information about all releases. Include links to copies or source control tags of the deliverable; links to epics, stories, or tickets related to the release; and a summary of the release and changes since the last release.

As an Agile participant, you want to be transparent, so you want to publish these items somewhere accessible within your company, such as a Wiki or Google Docs.

Be Agile

You're not just adjusting your deliverables. You're changing how you think and how you act.

So be Agile. Know what you're shipping and what you're not (yet). Iterate. Seek and use feedback for your iterations. Say no in a positive way. ("If we do that, then we'll have to make concessions in XYZ.")

Think like a user and produce what they need. Think like a product owner and focus on requirements while planning for nice-to-haves. Think like a developer and plan your work to be shippable on a sprint cadence.

Are there things that you can automate in your tech doc process? Could you use scripts to check parts of the content? Can you set up a system that automatically builds updated outputs for internal stakeholders at some interval (each commit, nightly, weekly, etc.)?

What Should I Watch Out For?

Let's be clear: no methodology is perfect. Of course there are drawbacks.

As mentioned earlier, Agile will be harder to implement if you're producing physical deliverables, such as printed documents. You won't be able to iterate as often, but you could maybe do smaller print runs to give yourself a chance at more iterations. (That may not be realistic, but hopefully you get the idea.) You can still probably chunk out the production work into sprint-sized tasks.

If you're in regulated industries, you may face a lot of limitations on the ideas presented here for Agile documentation. Obviously, you've got a clear list of requirements that a product owner can rely on, and that gives you a starting point (that you've always been working toward).

Can you break down those requirements into stories that can fit into individual sprints? Maybe this will help you manage the workload or maybe it will be a formality that hinders you from getting stuff done.

In Agile, a backlog is a useful tool to help you track and prioritize, but it can also become an unattainable wish list that weighs on the conscience of a thorough technical writer. This can happen when you have a plan of improvements to make to your docs and organizational priorities make it so you never get to the planned improvements. It can also happen when your backlog grows faster than you can knock out items on it.

A practical word about the backlog: If you're an Agile technical documentation team, then it's fairly easy to set up your own backlog. If you're embedded with design, development, and QA, maybe you can have your backlog combined with the entire team's backlog. If not, then things might get a bit more complicated, but think about using tags or labels in your team's ticketing system as a way to build out your backlog.

The good news is that a well-documented backlog may make it easier for you or your manager to make the business case for a new hire. And if the backlog is in really good shape, that new hire will know exactly what needs to be done when they start.

Maybe next time, you'll hear your Agile colleague say, "The big software release is only six weeks away, and we'll deliver technical documents then, too. No problem."

John Collins was a senior technical writer for five years at Rosetta Stone in Harrisonburg, VA. Hired as the second full-time technical writer in the company, he was team leader and Scrum master of the eight-person technical communication and localization team. Now senior UX content strategist at Rosetta Stone, John's role sits at the intersection of user experience, content strategy, technical communication, and localization. He blogs at www.intersectUX.com/blog and you can find him on Twitter jrc_collins.