Jaa

Update or rewrite: how do you decide?

  • Artikkeli

This is a common scenario for technical writers: there is existing content, let's say for V1 of a product, and the same content needs to be provided for V2. Do you limit your work to making changes to the existing content for technical accuracy with V2? Or do you start with a blank slate and design a new doc, generously copying content from the old where applicable?

Here are some of the issues I consider when making that call. The first two are fairly cut-and-dried, but after that it's more subjective.

  • How much is the product changing?  Is the next version of the product going to be so fundamentally different that very little of the old content is relevant or accurate? If yes, then you don't have much of a choice - start fresh, and take advantage of what's already written where you can. Most product versions aren't so dramatic or drastic though.
  • How much time do you have?  If there isn't enough time in the schedule to do a new document, then you update the old one. Even if the old doc really needs a rework. You don't want release delayed because the documentation isn't done or incomplete/missing documentation at release. When the next version just has incremental changes and a handful of new features, and you have plenty of time for documentation, then you go to the next question.
  • Is there any feedback or customer data on the existing content? If you've only heard from customers that they love the existing doc, it doesn't mean that you shouldn't evaluate the doc for possible reorganization or structural changes or different approaches to topics, but it does indicate that you should carefully consider the potential impact of major changes on customer satisfaction.On the other hand, suppose customer feedback has been mixed or trending toward negative. This, then, is a great opportunity to start over with a new design that will aim to address any customer complaints or confusion. Sometimes you won't have any real data other than "nobody has complained about it." Then you go to the next question.
  • Can you make it better? Different is easy; better can be challenging. (How do you measure, for example?) Are you making changes to mark your turf or to improve the customers' experiences? Can you articulate why you believe the changes are a good idea and what you expect the changes to accomplish?

Even when (1) the product isn't changing that much, and (2) you have plenty of time, and (3) there's really no feedback or data, and (4) you have definite ideas for improvement -- you still want to consider whether reworking this doc (rather than just updating) is the most important thing you could be doing with the time you have.