Category: Reference

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

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 achieve common tasks.

Reference material should be austere and to the point.

Normally Reference guides have no place in the wiki as they should be part of the project documentation itself. Under very special circumstances it might be the case that Reference Documentation is stored as an wiki article for a short time e.g. upstream project currently has no place for said documentation or the first draft for a reference document will be written here before being transferred.