How to Develop Agile Documentation

Traditional software documents are created from the top down. Figure out who will be doing what with the software, then write documents aimed at each category of users, explaining how to use every bit of functionality they should (theoretically) need to use. This method really doesn’t fit in well with modern software design. So how can we use basic concepts from Agile methodology to develop Agile documentation?

Stop thinking in documentation chunks

User manuals can be death to Agile documentation. They require top-down design to be coherent and useful. If you don’t need to create user manuals, don’t. Instead, create single-topic pieces of documentation, each of which respond to a single user need. Another way to think about it is that each piece of documentation should answer a single question.

Agile documentation answers questions that users are asking.

Have a documentation backlog

The concept of a functionality backlog is key to Agile methodology. Developers change or write code based on a backlog prioritised by the Product Owner. Likewise, create a documentation backlog, and prioritise it.

Develop new documentation based on what users most need right now. In every piece of software, there are areas of functionality that users will have more trouble using. These are what you need to be adding to the documentation backlog.

Your documentation backlog consists of information that users need and can’t currently obtain.

Anyone can update documentation

Using doc tools often requires a whole specialised skill set. That’s part of the reason technical writers exist – to wrangle the doc tools into submission. But one of the key tenets of Agile methodologies is that any team member should be able to take over others’ role when need be.

Use tools that everyone can easily get a handle on. In a software dev environment, this still gives you a lot of options. Wikis, Confluence, and markup languages like reStructuredText and Markdown are popular text-based tools. I favour markup languages, because I think they better support Agile methods. But that’s only if you’re using text-based doc; you might find that instructional videos, for example, better suit your audience.

Create your documentation using tools that your whole team can easily skill up on.

Include in Sprint planning

Every Sprint planning session should include these questions:

  • What’s the highest-priority task in the documentation backlog?
  • Will coding changes make existing documentation incorrect or obsolete?
  • Will our coding changes cause users to ask new questions? If so, what are they?

Make sure that Sprint planning includes documentation.

Harness loosely to coding work

I say to harness documentation loosely to code development because it can be tempting to document every code change for users. This is often not the best use of a technical writer’s time.

A technical writer’s Sprint objectives should look something like this:

  • Answer the highest priority question in the doc backlog.
  • Update the three pieces of documentation that code changes this Sprint will make incorrect.
  • Write down the new questions created by the Sprint work, provide skeletal answers for future reference, and give them to the Product Owner for adding to the doc backlog.

Link documentation work to the doc backlog and Sprint code work.

Create small Sprint tasks

Keep each task under one day’s work. Team members can clearly see how the Sprint work is progressing. If a person is absent for a day or two, their tasks can be reassigned more easily.

Describe concisely the work to be done, so that anyone unfamiliar with the documentation can still pick it up.

Example

MEH – Update Login screen doco
GOOD – Modify How to Login article with new OTP option

Why the second option’s better:

  • Clearly indicates the exact article to be changed (doesn’t assume lots of familiarity with the doc suite).
  • Links the update to a new piece of functionality.

Keep documentation tasks small and descriptive so they’re easy for anyone to pick up.

Treat docs like code

Where possible, use the same processes for your code and documentation. This includes:

  • Control: add your doc source files to your code repository and use the same branches.
  • Building: automate doc builds on the same schedule as code builds.
  • Testing: include doc in automated, manual, and user testing.

This is where markup languages can come in handy. They lend themselves well to using code repositories and automated builds.

Streamline your processes by integrating docs with your code.

Key points to remember

Develop Agile documentation by:

  • Answering users’ questions.
  • Using a doc backlog.
  • Making your doc tools accessible to the whole team.
  • Including it in Sprint planning.
  • Link doc planning to code planning, but loosely.
  • Creating small, descriptive tasks.
  • Using the same processes as code.

 

Leave a Reply

Your email address will not be published. Required fields are marked *