How does one avoid incomplete changes to documentation?
Having encountered errors in technical documentation that almost certainly came from incomplete editing after copying from earlier documentation, I am curious about what techniques can be used to avoid this problem.
Sadly, it seems difficult to strictly apply the programming principle of Don't Repeat Yourself since much of the documentation is written in a human language which is less friendly to automated macro insertion.
(Automatic consistency might be possible for tables and diagrams with a regular structure, and often such features could be generated automatically from lower level data. This would not necessarily guarantee consistency with the actual product, but [barring bugs in the translation software] descriptions would be consistent from the lower level upward. If this extended down to the hardware description language, only translation bugs would be an issue, but I do not know if that is practical and such would apply less to architectural documentation than to implementation documentation.)
Using macros as much as practical would help (e.g., many numerical substitutions could be automated), and it might be possible to include dependency information to highlight when changes in certain parts of the document (or system of information) might require changes in other parts of the document. In some cases, automatic generation of documentation that only needs modest modification for readability might be practical and minimize the use of copy-paste.
What practical techniques help avoid incomplete changes to documentation?
This post was sourced from https://writers.stackexchange.com/q/10681. It is licensed under CC BY-SA 3.0.
1 answer
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.
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.1 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.
1 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.
0 comment threads
0 comment threads