Post History

Source: https://writers.stackexchange.com/a/10684
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

This is a hard problem. Unless your company has the resources to do full reviews of all the documentation on each release -- and if they do, I wonder how they stay competitive -- then you are at risk here. In my experience you can do some things to _address_ the problem when it happens, and some things to _reduce its chance of occurring_.

Here are techniques I've used to find and fix missing updates:

- Quick visual scan of the most-relevant documentation. This isn't a full review (you probably don't have time), but I try to at least pass my eyeballs over each page in related documents/sections to allow for the chance that something will jump out at me. This actually happens.

- If a feature (API function, GUI element, schema element, etc) was changed or removed, I search the documentation for relevant keywords like the name of the function/element (however we talk about it in the documentation). This helps find stray references, such as the documentation of some _other_ function that compares it to the one that changed. This has helped me catch cases like "The X function does blah blah blah; it's similar to the Y function except..." where Y changed.

- If behavior changed then test cases probably also changed. I try to chat with the testers who'll be testing the newly-changed feature to find out what _other_ test cases they had to change. (Note: even though I have access to their test-case repository, I find it easier to spend a little time talking with a tester instead. The testers know their test cases way better than I ever will. For similar reasons, they generally ask me what significant changes I made in the documentation.)

- On a project with multiple writers, I choose peer reviewers who've worked on parts of the documentation that I haven't spent as much time on. They'll notice "oh if that changed then this other thing in 'my' doc needs to change too" before I will.

Here are some techniques I've used to prevent, or at least reduce the likelihood of, this problem. Think of this as _defensive writing_:

- In the spirit of "don't repeat yourself" (DRY), if I need to include the same information in more than one place, I try to abstract it out into one blob that I can include by reference in all places it needs to go. Writing fragmented documentation like this is harder (you have to be careful to make sure that your blob remains valid in all contexts), but this level of repetition doesn't happen _that_ much in my experience. But it happens some, so use include tools when it does.

- Sometimes you know when you're writing something that it's interconnected with some other part of the documentation. Use comments (or whatever annotation mechanism your tool supports) to add findable reminders to yourself. Comments aren't just for code; they can be useful in doc source too. (My source is XML; your mileage may vary.)

- I haven't done this one yet in "production" (only as a test), but [annotate your screen shotes](https://writers.stackexchange.com/q/3785/1993).

- When it comes to your bugs database, be nosy. I am automatically copied on all bugs in certain components, and I review new bugs often and add myself to the CC list on any that look like they might affect me. Yes, this generates a lot of email, but it's worth it to catch notes from testers, and also ones from developers who found they had to change something else in order to implement this. I get a lot of my best information from Bugzilla notifications. 

- Be more thorough in initial project estimation. At the beginning of the release-planning cycle, when the product manager, development team, et al are laying out the work to be done, you probably -- if you're like most people -- added a line to the project plan that said something like "update doc (N weeks)". But if you do a little more up front, you can avoid some problems for yourself _and_ for the testers.<sup>1</sup> While the developers are doing their analysis of what will change if they do such-and-such, you can be doing the same for the doc. So instead of that "update doc" line you might have items like "document new feature X", "update feature Y (that changed because of X)", "update doc of example that uses Y and Z", and "review doc of Y for impact". While you're talking with your friendly tester about this, you might learn that your tester knows that some part of Z is going to have to change too, so you can start thinking about that earlier. In other words, the more your team talks about the impact early on, the easier it will be for you to make your doc changes systematically and with less of a panicked rush at the end.

<sup>1</sup> You may be getting the idea by now that I think the testers are your natural allies. They are. You and they are often at the end of the information pipeline, not because anybody meant to exclude you but because people focused on a narrow task don't always realize the implications themselves. Work together.

Original score: 2