Post History

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

It depends, but probably you want the distributed approach where the chapter on X tells you everything you need to know about X, even if some of that is only relevant if you're using feature Y. However, if Y is a corner case or involves a _lot_ of changes to several other features, you might be better off collecting everything about Y in one place _and linking to it from every other chapter it touches_. Don't just put it in its own chapter and say nothing in the others, though; that can lead to surprises when users who jumped straight to X later find out that they should have done X' because they're using Y.

On top of this, one approach my team uses is to have a section of the doc set (an HTML bundle of all the individual docs) that describes new features in this release. Each new feature gets a high-level description of what it is and when you might use it, ending with links to the relevant places in the "main" docs. People interested in "new feature Y" can go there for easy access to the information (via links), but the main content is in the other docs.

Original score: 2