Post History

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

[This answer](https://writing.stackexchange.com/a/42850/1993) covers a single work like a paper well, and what it says applies to larger works too. Correctness and clarity are the most important factors in any technical work. For larger works, such as a new section in a large documentation set, I look for some additional things:

- **Consistency of style:** Does this part fit seamlessly into the larger body of which it's a part? Ideally there is a house style guide, so what we're checking here is adherence to it. But, beyond that, if there are themes running through the larger work, such as an example domain that all the examples use, does this piece fit into that?

- **Cross-references:** Very few pieces of technical documentation exist in a vacuum. Does this new part link to (or reference) other parts where needed? On my team, for example, we have reference pages for all the commands, functions, system tables, and so on that our product supports; when reviewing task/guide documentation, I expect to see links to the relevant references pages.

When providing feedback on a larger work in its entirety (which is a huge task), I pay particular attention to:

- **Table of contents:** Do the order and divisions into subtopics make sense? Is the structure reasonably balanced? For example, I don't want to see 30 top-level topics and then two topics each that have children out to six levels. You shouldn't impose arbitrary limits (I said _reasonably_ balanced), but if your organization seems really out of whack, that can signal problems with the content itself, too.

- **Index** (if present): I'll scan to see if similar things are in fact grouped together; I don't want to see "get" (15 subentries), "getting" (12 more), and "retrieving" (3 more). I look for a good mix of nouns and verbs. I'll pick a few entries at random, follow them, and see if where I landed makes sense.

Original score: 4