Post History

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

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?**

Original score: 3