How do I approach rewriting an entire user guide in an agile environment?
I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The company adopts the agile development process, and a sprint typically spans three weeks.
I've been thinking how I should approach this task. Should I be writing the guide using whatever is in the system at the time of writing, then, when all the sections are complete, incorporate what was missed in the release notes? Or should I be writing the sections involved in the sprints first, then work on other sections when I am free? Are there other better approaches?
This post was sourced from https://writers.stackexchange.com/q/12440. It is licensed under CC BY-SA 3.0.
2 answers
I've written manuals under a Scrum process, so I'll describe what worked for my team.
I'm going to treat your task as if you're writing a new book. From your description, you'd be replacing the vast majority of the content anyway, so better to think of it as a new book (for which you might be able to take advantage of the occasional previously-written bit) than an update.
First you're going to need to come up with an outline or broad plan of attack. What topics do you need to cover (in what detail)? Is the organization of the original book workable now, or do you need to re-arrange things? In (or prior to!) your first sprint, come up with your initial list of work to be done. Start thinking about how it breaks down into stories. (This is the initial backlog; you should expect to discover more things that will need to be covered as sprints progress. Use your usual process for managing those; in our case newly-discovered issues got added to the backlog and considered in the next planning session.)
During sprint planning, you (plural) should identify which of these tasks to work on now -- due to urgency, or code stability, or whatever other criteria are at play in your team.
During each sprint you should be working on the following types of tasks:
Writing new material (scoped to fit the sprint, less the other work you need to do in this sprint)
Addressing feedback from what you wrote in the last sprint (you should be getting feedback from developers, testers, and user representatives as you go)
Updating prior work for changes in the code, if applicable -- if you're working on the doc alongside the developers working on the code, there are probably going to be changes that you'll need to address
During the last couple of sprints before the release, start thinking about what will need to go into the release notes. I assume that the release notes are a team project, as they usually include things like a bug list from QA. Your part of this is to identify what is important enough to document that isn't going to make it into the user guide, and then figure out how to address that in release notes. This should result in a story for your last sprint, with the team agreeing on the tasks to be included.
0 comment threads
A user guide is an important result related to your final product and should be treated as such. If the software that is being detailed is in development you you obviously can't know everything that will happen exactly in advance, but you can treat this like you would treat writing a book:
- start with a rough outline
- work on each chapter as far as you know
- ask your beta readers / coworkers / users to get feedback
- rewrite every chapter that needs rewriting
You should plan activities in each sprint that are related to these tasks. This means in the first sprint (or sprints if it's a really big old project) you would work on the outline. In later sprints you would need less time for the "outline" story and more time for the "detail existing chapters" story. Then you will need even less time allocated to the "outline" and still similar amounts of time for "detail existing chapters", plus a bit of "collect feedback". Then you will start to remove the tasks that are related to the outline and to the detailing and replace them with collecting and incorporating feedback.
In the end you have an evolving document that gets some ideas from the existing documentation and evolves alongside the application.
The same approach applies to updating an existing user guide for software that isn't rapidly changing at the moment. You take the original documentation as a starting point, look at what changed since the document was last updated, start updating parts and collect feedback on your progress.
In any case it's important to ask users in one of the first sprints to give you feedback on the current state of documentation. What are they missing? What are they expecting from a user guide? What was good or bad about the old one?
You are in the fortunate situation to have an existing example as orientation, a rough guideline of what needs to be included and probably users with years of experience in using your software and the existing documentation. Make sure that you are talking with your users and not wasting time on stuff that has been changed multiple times by preparing properly in the first sprints and this will be a nice technical writing project.
0 comment threads
0 comment threads