Reference Manual writing guide

Reference Manual writing guide

The reference manual is the place to document the available tools, settings and functionality.

A manual entry about a tool or a setting should contain:

• a screenshot of the menu location
• in case it is not clear: where the tool/setting is
• what the tool/setting is
• what the tool/setting does
• in case it has a last operator entry: all the settings from the last operator
• and in case it is not clear: how to use it

How to use a tool can in some cases mean to write a short tutorial about the useage. But it should be really as short as possible, for just the tool. And not end in a general CG tutorial. Unfortunately something that I have also seen in the Blender manual before.

Examples can be found in all chapters written by me, for example 3.1.1 - 3D View by tools

The reference manual is not the place for tutorials and opinions though.

For example, this one, taken from the Blender manual:

"Uses Simple Direct Media Layer API from libsdl.org to render sounds directly to the sound device output. Very useful for sequencer strips editing."

For the reference manual it is not of interest if the tool or setting is useful or not. It is just of interest where it is and what it does. I think you can imagine how the manual would look like when every item would contain an additional entry about where somebody thinks that the tool or setting is useful.

You can also read other biased opinions in the Blender manual. Like that Angle based is better than Conformal unwrapping. Which is not only utter nonsense, it's just two tools with somehow equal purposes but different results. But simply does not belong into a reference manual.

Or a detailed tutorial how to use Vertex parenting, and do animation with it. As told, tutorials does not belong in the reference manual.

What is also to avoid is links to other chapters. Also something that you can find in the Blender manual very often. "For explanation see chapter ... "

When some information is relevant for the current entry, then this information belongs into this entry. And should not link to other locations in the manual. And when this means that you need to write the same thing 20 times, then write it 20 times. This is for example required for all the last operator panel entries for lots of tools.