: 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
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?
More posts by @Alves689
: The core of narrative writing is strong verbs. Descriptive writing might have some verbs, usually weak ones, but the main tools are nouns and adjectives.
: How Many Poems Does a Chapbook Typically Contain? I'm sure it varies a bit (both in length and in number) but, on average, how many poems does a chapbook contain?
1 Comments
Sorted by latest first Latest Oldest Best
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.
(I should mention that on my last agile team the release notes were actually managed by the QA team, not by the technical writers, so my advice on that point is based on what I've seen/heard others do, not on direct personal experience.)
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.