8 Tips for Creating Agile Documentation

Transitioning to agile documentation is often more difficult for a company than transitioning to agile software development. That’s partly because a lot of today’s technical writers learnt their skills in the days of waterfall methodology. It’s also because for many years, there was a dearth of training in agile documentation; leading to a lot of confused writers and software companies.

Agile documentation isn’t that hard, though, once you get your head around applying software development methodology and concepts to technical writing. Here are a few tips for making your documentation truly agile.

1. Use agile tools

You can use almost any documentation tool in an agile environment. But one of the key tenets of most agile methodologies is that any team member should be able, in a pinch, to do any job. Ideally, use a documentation method that developers and testers can pick up quickly and easily. Markup languages fit this requirement; most online knowledge bases could also suit.

Google has recently announced Docsy, a website template specifically designed for technical documentation. You might find that this fits the bill too; I’ll be exploring it in a future blog post.

The documentation tool you use should ideally be able to integrate, at least partially, with code repositories and automated build and test systems.

Use a documentation tool that doesn’t need much upskilling and can integrate with your build and test processes.

2. Attend team meetings

Agile software development often involves fast changes to functionality. The documentation can quickly become out of date if the technical writer doesn’t keep abreast of modifications. Attend all team stand-ups and design meetings to keep track of design changes that might affect documentation.

Stay in the know; understand functionality changes as they’re being designed.

3. Have a functionality map

When creating Agile documentation, it’s important to map functionality to your documentation. This has a few benefits:

  • Provides you with a quick reference at the start of a sprint so you can estimate the documentation changes needed.
  • Allows other team members to take over a documentation role for a few days or weeks with minimal confusion.
  • Highlights gaps in documentation.

How you choose to map this out is up to you. It needs to:

  • Be easily accessible and updateable.
  • Link, where possible, with design documentation. A UML diagram might fit this bill.

Keep a map of software functionality to documentation, so you can track doco changes needed.

4. Write in slices

“Begin at the beginning,” the King said gravely, “and go on till you come to the end: then stop.”

Alice in Wonderland, by Lewis Carroll.

We’re so used to following the King of Hearts’ advice that adjusting to a new methodology can be a trial. Agile methodology requires a different documentation strategy. Some people still recommend ‘lagging’ doco behind development; I think this is a bad idea. If you’re in on design meetings and understand the functionality changes for the current sprint, you should be able to write or script the required documentation with minimal actual software to refer to.

Agile software development usually depends on creating ‘vertical slices‘ in each sprint. Use the same concept in creating your agile documentation. Where possible, only document the functionality that will be created in your current sprint. This may mean that you’ll need to modify a particular section of the documentation multiple times before the feature is complete; it might seem like redoing work, but it’s almost exactly like the code – you’re refining as you go. Once you’re used to it, working in vertical slices is quite rewarding because the result is immediately useful.

If your software developers are using the ‘vertical slice’ method of sprinting, use the same concept for developing your documentation of the features they’re working on.

5. Don’t document the product

Document what users need to know. This might sound like the same thing, but it rarely is in practice. Your users need to know how to complete their tasks, which in the real world might differ significantly from hypothetical use cases.

You need to be focused on user needs rather than ticking boxes.

6. Improvise

One of the joys of agile documentation is that you don’t always have to do the same thing. You can try different ways of delivering documentation, and test user responses on the fly. For example, scripting and then recording a quick tutorial video for a sprint’s new functionality might be quicker and more useful than traditional documentation. Users didn’t like it? Try something else next sprint.

Don’t be afraid to try a new format for a piece of documentation.

7. Get and use feedback

The whole point of agile methodologies is to quickly respond to user demands and market shifts. Agile documentation shouldn’t be exempt from this requirement. Figure out ways that your users can access the new documentation and leave feedback about it. Try to gather two types of feedback:

  • active – something a user specifically does with the intent of giving feedback, like upvoting or downvoting an article, or adding a comment.
  • passive – feedback gathered from how users interact with an article; eg. social media shares, bounce rates.

Constantly gathering and using feedback is key to creating useful agile documentation.

8. Fail and learn

In the Agile world, it can often feel as though no one cares about documentation except technical writers. That’s not true, though. Users care deeply about documentation… when it’s not meeting their needs. One of my favourite concepts in Agile methodology is that it’s OK to fail. Failure is good. Failure is how we learn. If you’re truly producing agile documentation, you can quickly see which bits are being used and which bits aren’t. The bits that aren’t are failures – or to put it another way, learning opportunities. You might need to change your approach 3 or 4 times before you find the one that your users resonate with; but you’ll find it.

Use a failure to connect as a learning experience, not a reprimand.


2 Responses

  1. Great article Naomi, I will be sharing this with any technical writers I work with from now on.

Leave a Reply

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