Category:Reference: Difference between revisions

Reference is one of the five primary resource categories for the wiki.

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.

Content of this category should be moved to the manuals or https://nix.dev

• NixOS manual
• Nix manual
• Nixpkgs manual
• Hydra manual

Comparison to other resource page types

• If information is more encyclopedic (with a similar scope and tone to pages on Wikipedia), a page would be considered a pedia.
• If information is less encyclopedic and more similar to a compendium, study guide, or a bibliographic guide, a page would be considered a guide.
• If information is more about direct instruction to achieve a specific task, a page would be considered a tutorial.
• If a page is more just a set of tips and tricks (less instructive than a tutorial), it would be a cookbook.
• If a page is a detailed reference (like a man page or full software manual), it would fit under references.