Creating documentation in an agile environment
Published on 6 October 2022 by Andrew Owen (7 minutes)
Google for images of agility, and you’ll get dog trials. So let’s go with that analogy. If you create written content for software, going from waterfall to agile can feel like being a dog unexpectedly facing an obstacle course when it’s time for walkies. And instead of once a day, now walkies is every hour. Maybe not the best analogy. I’m not sure what the dog equivalent is for having to throw away all the work you’ve been doing for the last week and start over. Ok, let’s start over.
Agile is a software development philosophy that defines itself in opposition to Waterfall. According to the manifesto, agile values:
According to Zed A. Shaw, who rejects all programming methodologies (there’s even a T-shirt), when they say they value:
Your experience of agile will probably fall somewhere between the two. In my work, I’ve mostly encountered the Scrum project management methodology. Without going into detail, you typically have a software development cycle that releases to customers every two weeks. This creates enormous headaches for technical writers and instructional designers.
When Scrum works, the product owner communicates the customer requirements, the project manager manages the team, the scrum master managers the project and the team deliver something at the end of a two-week sprint. The sprint starts with planning to work out what can be delivered and ends with a demonstration of what was created and a retrospective on what worked and what didn’t. This approach means that product owners can’t just tell the team what to deliver. Which has led to the creation of the Scaled Agile Framework (SAFe) in an attempt to take back much of that developer freedom. But I digress.
The main difference for the technical writer or instructional designer from waterfall software development is that, typically, there is little to no time between completion of software development and release to customers. This means that you need to be creating your documentation and training materials while the software is being developed. And that means that you had better be prepared to throw all your work away and start over when things change.
One of the other aims of agile is that you deliver software that works, and then you go back and refine it. This means that your documentation and training materials will need constant revision. Sounds like a nightmare? It is. So, how do you cope? From a planning perspective, you need to be in the planning meeting at the start of the sprint. You need to be in regular contact with the developer working on the feature that you’re writing about. You need to go to the demo. You need a software environment where you can test the software while it’s in development.
You’ll notice I said the feature (singular) that you’re writing about. The biggest change to how you work is that you need to break down your content to be as atomic as possible. In agile, features are typically described in a user story. For example:
As an administrator (role) I want to be able to see a list of inactive accounts (task).
And that’s the paradigm shift. Instead of describing how the software works, typically based on an exhaustive description of the user interface, you break your content down into how to accomplish specific tasks. The old way used to result in manuals the size of telephone directories. The new way means you should result in a self-contained topic.
Created at IBM and managed by Oasis-Open, the Darwin Information Typing Architecture (DITA) was fashionable in technical writing circles for a time. I always found it a headache to use, but it does have some solid reasoning behind it, notably the concept of topic-based authoring. Instead of writing a whole book, you write a topic which can be one of:
The idea is that you then take these topics and assemble them in to manuals, online help and so on. In practical terms, the one you need to concentrate on is the task. Technical writing and instructional design don’t really seem to have caught up with the idea that everyone who uses their software has a high-speed broadband connection, and knows how to use Google.
Rough as it is, if you’re in a hurry, you can link to a Wikipedia article to provide concept information. The same goes for general reference information. For software specific information, you may need to create a reference topic. But there are special cases, like API schemas, where it’s better to have a dedicated interactive developer portal than trying to present that information in online help or manuals.
For the instructional designer, this means not replicating the work of the docs team. Courses should be able to link to concepts and references in the documentation. This requires that the documentation be publicly available, or that docs and training are hosted behind the same sign in. Modern users prefer to consume videos than read manuals, and those videos should be short. Three minutes is ideal. Fifteen minutes is the maximum. If it takes more than that, try to break it up in to smaller related topics.
If the agile process is going well, the software will change frequently. This means that screenshots and videos will age rapidly. Remember that your audience is smart, but busy. If there are multiple ways to achieve a task, give them only the simplest way. Don’t give them screenshots of simple user interface elements like menus and buttons. If you have to use a screenshot, crop in as tightly as possible on the relevant content. Try to use natural descriptions instead of callouts.
Being involved in the development process gives you the chance to influence the software. I’ve always argued that software that’s hard to document will be hard to use. If you spot problems in the user interface, let the developer know. But be gentle. We all have to work within constraints, and often the quality of the work we produce isn’t a direct reflection of us.
Next up is content reuse. Even though it saves hours of work, I’ve rarely seen single-sourcing well implemented. Boilerplate text should exist in a central location. Product names and UI elements should be variables. Terminology should be consistent across products and defined in a glossary. And if you’re not going to create an index, then you had better have an excellent search function.
Ideally, you also want to be able to derive data from search terms to see what content your audience is looking for. But even the simplest analytics can tell you if the content you created is being consumed. If you have a topic on a feature that no-one is reading, it can mean several things:
For instructional designers, you’ll have to give up your traditional linear approach to content development (analyze, design, develop, implement, evaluate). But you do have some choices for what to replace it with:
I’m not an instructional designer, so I don’t have any recommendations there, I just know that the ADDIE model doesn’t work. And I think that’s probably enough to digest for now, but I may well revisit agile instructional design in a future article.
Image: Original by f/orme Pet Photography.