7

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?

4
  • 2
    Team up with a skilled user of the system being documented.
    – SF.
    Jul 21, 2014 at 13:41
  • 2
    Welcome to Writers! Jul 21, 2014 at 14:37
  • I would start by utilizing guides that are already out there and tailoring them to your organization.
    – James
    Jul 22, 2014 at 16:53
  • Are you in contact with actual users?
    – Jasper
    Mar 4, 2018 at 21:34

1 Answer 1

6

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.)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.