Blender Documentation: Last modified July 3 2003 S68
<<< Previous | About the Blender Documentation Project | Next >>>

# The Blender Documentation Project styleguide

To maintain consistency throughout all Blender Documentation, prospective authors are kindly requested to abide by the present Style Guide.

## General Guidelines

Blender documentation should be written in clear, concise, idiomatic and correct English. It should be adequately subdivided into chapter, sections and subsections.

The logical subdivision of Core documentation is dictated by the Documentation Board.

The logical subdivision of contributed Tutorials is left to each author, but it is strongly advised that the authors provide a list of up to five keywords from the Section called Keywords to classify their work. Please type Keywords exactly since they will be indexed for searches.

Tutorials should contain an abstract of up to 300 words briefly describing topic, aims and contents for quick browsing.

## Images Guidelines

The use of images in the documentation is essential. The PNG and JPG formats are highly preferred. GIF and other non-free formats are prohibited. Uncompressed formats like TGA are discouraged.

### Floating Images

Float images should bear a caption and be referenced in the text. Please refrain from wording like the next picture or the following figure. Use cross references. Cross references are described the Section called Cross references

The usage of unreferenced images is discouraged. If you have an image you don't know how to reference either the image is unnecessary or your text is unclear.

The Documentation, both Core and Tutorials, is to be published both on the web and as printable matter. Dimension/resolutions should be, at maximum, as reported in Table 1 (see.. crossreferences!)

Table 1. Image resolution/dimensions

Width [pixels] | Height [pixels] | Resolution [dpi]
--- | --- | ---
1000 | 768 | 150
800 | 600 | 125
640 | 512 | 100

These resolutions/sizes guarantee that printed images won't be larger than 17cm and hence fill an A4 printed page.

The use of images larger than 800 pixels is strongly discouraged anyway, since they are too wide for comfortable reading on a web browser.

One of Blender's most prominent features is that the Interface is fully OpenGL and scalable. This is great, but will unfortunately result in many differences if a number of users resort to screen dumps to show peculiar material settings, texture settings and the like.

To allow for both clarity and uniformity you should dimension the interface so that the RED slider in the material window is 18 pixels high. This is what Blender produces if you use a 1024x768 screen resolution and press the 'home' button to set the default button size.

If you use a larger resolution, please drop down to 1024x768 for screen capturing. I hope no one out there has smaller screens!

Screen captures must come in a LOSSLESS format, so use PNG.

### Inline Images

Inline images showing Blender icons are welcome and make description much clear. Since these are STANDARD images, please refrain from making your own, but download the complete set provided by the Documentation Board

### Inline Smileys

Official Documentation is not a place for smileys. (Humour is another matter, of course you can be humorous!)

## Tables

Tables are an appropriate way to display lots of data in a clear structured way. They can be a valid alternative to screen dumps to show some setups.

Tables, like float figures must have a caption and must be referenced in the text.

## Code

DocBook has its nice environment for Python/C/whateverlanguage code chunks.

Code chunks, like float figures must have a caption and must be referenced in the text.

<<< Previous | Home | Next >>>
Learning DocBook/XML | Up | Documentation Style in Practice