Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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?

share|improve this question
2  
Team up with a skilled user of the system being documented. –  SF. Jul 21 at 13:41
2  
Welcome to Writers! –  Neil Fein Jul 21 at 14:37
    
I would start by utilizing guides that are already out there and tailoring them to your organization. –  James Jul 22 at 16:53

1 Answer 1

up vote 3 down vote accepted

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

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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