Reference Guide

Reference guides are technical descriptions of the machinery and how to operate it. page

Reference guides have one job only: to describe. They are code-determined, because ultimately that’s what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them. Reference material is information-oriented. By all means technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts, or how to achieve common tasks. Reference material should be simple and to the point.

Note that description does include basic description of how to use the machinery – how to instantiate a particular class, or invoke a certain method, for example, or precautions that must be taken when passing something to a function. However this is simply part of its function as technical reference, and emphatically not to be confused with a How-to Guide – describing correct usage of software (technical reference) is not the same as showing how to use it to achieve a certain end (how-to documentation).

For some developers, reference guides are the only kind of documentation they can imagine. They already understand their software, they know how to use it. All they can imagine that other people might need is technical information about it.

Reference material tends to be written well. It can even – to some extent – be generated automatically, but this is never sufficient on its own.