Post History

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

In order of descending utility, IMO:

1. Project/feature/bug tracking software, for well-defined product changes. A must.

2. Email notification to other writers (broadcast) that refers to entries in #1 or to a wiki entry describing the doc change. The email summarizes the context & change enough that other writers can tell whether it affects them. The wiki entry provides details. Wiki **tags** provide organization/classification and facilitate search/lookup. Tags can include project names/numbers, bug numbers, and other thingies in #1.

3. Comments embedded in the doc can help point out details and locations of some doc changes. Source-control change logs can also help for this, but are coarse-grained.

#1 is preferable, when it can be used. Many doc changes reflect product changes, including bug fixes and new features. The doc changes for these can/should be managed together with the changes to the rest of the product (the doc is of course part of the product).

#2 supplements #1 - it is for anything that doesn't fit in #1 and doesn't need to be in the doc itself. But it is often possible for #2 to reference thingies in #1. An example of content for #2 might be a doc reorg - but even then it is often better to create a product project for the reorg, i.e., a doc project, and track it in #1.

#3 can help a writer who visits the result of your changes later. It can point out things that are not obvious and are specific to particular content - like good code comments.

Original score: 2