テンプレート:RefBox/guidelines

Guidelines

Below are guidelines for laying out a reference item and the types of information used to document it.

• Types marked ESSENTIAL are crucial information and should be included for every reference item, as long as they are relevant for that particular tool. Items without this information would not be useful as a reference.
• Types marked RECOMMENDED should really be included, but aren't 100% necessary for the reference item to go in the documentation.
• Types marked USEFUL are useful information that are nice to have if relevant and applicable.

Name of the tool or option (as in the Blender UI)

Mode: Type of Mode (ObData type) ESSENTIAL

Panel: Context → Panel Name ESSENTIAL (if the tool has options in a panel)

Hotkey: A ESSENTIAL (if a hotkey or hotkey sequence exists)

Menu: Menu → Menu ESSENTIAL (if a menu option exists)

Description

A concise overview of what the tool does, from an artist's perspective, including what sort of input it operates on (eg. 'objects' or 'selected edges'). Detailed technical info shouldn't be here. ESSENTIAL

Options

If a tool presents additional options either as a further menu, or popup buttons or as buttons in panels they should be described here. (eg. the subdivide tool's options for the number of cuts, or the way it cuts corners of quads)

The Definition list markup can be useful here to describe multiple options if there is a lot to write about:

; Option name
: description and info goes here

↓

Option name

description and info goes here

ESSENTIAL

Examples

Example images or text to demonstrate how this particular tool can be used, or what effects it has. This should be a brief demo, not a tutorial. RECOMMENDED

Technical Details

Extra information that's not crucial to an artist using the tool as a 'black box', but that may be interesting or useful for someone more technically-minded to gain further insight and understanding into its use. (eg. formulas and graphs for light distribution and falloff) USEFUL

Hints

Tips or tricks that may come in handy when using this tool or combining it with other tools. USEFUL

Optimizations

Methods for optimising usage, either for speed of operation/rendering, or for visual quality, or for ease/speed of use. USEFUL

Limitations & Work-arounds

If there are any limitations or problems with the tool as it's currently implemented, it can be a good idea to mention what they are, and if there are any ways users can work around it. (eg. the mesh bevel tool only bevels the entire mesh, not a selection. This can be worked around by separating the needed faces into a separate mesh, or using the bevel center script). USEFUL

See Also

• Links to other wiki pages of related tools, options or theory that would be useful for someone using this tool to know about, in an unordered list. Web links are probably even ok here too. RECOMMENDED