From BlenderWiki

Jump to: navigation, search

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

People completely unaware of MediaWiki Syntax can also refer to the official MediaWiki Docs

General Guidelines

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

The logical subdivision of Core documentation is dictated by the Documentation Board. No new pages are expected to be added except after approval.

The logical subdivision of any contributed Tutorial(s) is left to each author.

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

Each page should have an appropriate template as the First line to show navigation aids and to which blender version the page is updated to. This is done via

 {{Page/Header|2.32}}

being of course 2.32 the relevant version number.

It shows


Furthermore, for long pages presenting several sections --some of which are relative to a different version of blender-- a different template is available

 {{version|2.32}}

This should be placed immediately after the section/subsection title, as displayed in the section immediately below.

At the bottom of each page there should be a navigation aid footer

 {{Page/Footer|previouspage|followingpage}}

Showing like




previouspage and followingpage should of course be valid links to proper pages!


Templates

Blender 2.32+

There are a limited set of templates defined by the docboard, including note boxes, Key templates, and more. You are kindly requested to use them and only them.

The list of templates is here Templates


Reference Material

When writing reference material such as the user manual, please use the Template:RefBox template, and the associated sub-heading structure. This helps to keep the manual consistent, with common information in well-defined and easily recognisable places, so that people can skim read to the information they're looking for more easily. See the Reference Box Guidelines for more information and a guide on how to use this structure. An example of the ReferenceBox is below:

Mode: Edit Mode (Mesh)

Hotkey: CtrlR

Menu: Mesh → Edges → Loop Subdivide...

It saves you and your readers time to use these templates as much as possible. There's no need to explain in lengthy prose "To utilise this tool, you can press the X key on your keyboard" when there's a nice picture of a hotkey in the header, in a consistent place where readers know where to find it quickly. The manual is not a novel, keep your writing concise and to the point!


Images Guideline

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

Images are uploaded to the wiki by using the appropriate http://mediawiki.blender.org/index.php/Special:Upload

link.

Floating Images

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

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

The Documentation, both Core and Tutorials, need to maintain consistency. Dimensions should be, at maximum, 800x600. The usage of images larger than 800 pixels is strongly discouraged since they are too wide for a confortable reading on a web browser.

The most prominent feature with Blender's interface is that its fully OpenGL rendered and scalable. This is great but will sadly result in many dis-uniformities if many users resort to screen dumps to show various types of settings like, peculiar material settings, texture settings, etc..

To allow for both clarity and uniformity you should dimension the interface so that the RED slider in the material window is 18 pixels in height. This is what Blender produces if you use a 1024x768 screen resolution in Blender's default screen setup and press the 'home' button --while in the button window-- 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! One way to capture screenshots at 1024 resolution while your display is at higher resolutions is to use the windowed mode command line options as follows:

  ./blender -w -p 0 0 1024 768. 

This will start blender in a window with the drawing pane at exactly 1024x768 pixels. The application frame will be larger because of the desktop insets. To capture the blender portion of the display you could use Gimp with a 'fixed' size select region (of 1024x768) and it will automatically capture the blender portion of the application minus the window dressing produced by the desktop.

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

If you need to highlight a given portion of an image (a button, a value, or a group of buttons/values) please use a yellow (R=255,G=255,B=0) frame 2 pixels thick all the way around.

Use Blender's default UI style.

Inline Images

Inline images showing Blender's icons are welcome and make descriptions much clearer. Since these are STANDARD images, please refrain from making your own, but use the set kindly provided by DocBoard.

Inline Smileys etc

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


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 for showing various setups.

Tables, as with floating figures, must have a caption and must be referenced in the text.


Code

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

Code chunks, as with floating figures, must have a caption and must be referenced in the text.


Documentation Style in Practice

This Chapter shows in detail an example of what we expect your Wiki pages to be.

Image Examples

Here's how to insert images in your pages, once uploaded to the server:

Normal Images

This is the easiest method to place images within your text, and at the same time the safest since you don't have to worry about floats.

[[Image:DemoImage1.png|none|frame|Demo Image number 1]]

Makes the image start on a new line, with all text cleared from it:

Demo Image number 1

Floating Images

Dummy image
This one is a bit more tricky, since you have to take into account this may look different at other resolutions/window sizes/font sizes than yours. To get an image to float to the right of the text, use this syntax:

[[Image:Dummy.jpg|right|thumb|200px|Dummy image]]

Put that code in front of the first line you want the image to appear next to!
To clear the text until the end of the image, use the following syntax:

{{clr}}

Inline Images

Inline Images like DemoImage2.png are even easier to obtain:

[[Image:DemoImage2.png]]

Images in Tables

When you have a set of small images that have some relation to each other, you can put them in a simple table:

{|
 |valign=top|[[Image:Manual-Part-III-materialRampsExample04.png|thumb|200px|none|No Ramp Shader.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample05.png|thumb|200px|none|Color Ramp.]]
 |valign=top|[[Image:Manual-Part-III-materialRampsExample06.png|thumb|200px|none|Both Color and Specular Ramp.]]
|}
No Ramp Shader.
Color Ramp.
Both Color and Specular Ramp.

More Help on Images

See this page for extensive info on the use of images: Images and other uploaded files

Tables

Tables can either be written in HTML or by using a much cleaner Wiki syntax:

 {| border="1" cellpadding="2"
 |+Multiplication table
 |-
 ! × !! 1 !! 2 !! 3
 |-
 ! 1
 | 1 || 2 || 3
 |-
 ! 2
 | 2 || 4 || 6
 |-
 ! 3
 | 3 || 6 || 9
 |-
 ! 4
 | 4 || 8 || 12
 |-
 ! 5
 | 5 || 10 || 15
 |}
 

creates

Multiplication table
× 1 2 3
1 1 2 3
2 2 4 6
3 3 6 9
4 4 8 12
5 5 10 15

To facilitate formatting there is a 'UM/prettytable' template pre-defined

 {| {{UM/prettytable|50%}}
 |align=center | 1 
 |align=center | 2 
 |align=center | 3 
 |-
 |align=center | 4 
 |align=center | 5 
 |align=center | 6 
 |}
 

Yielding

1 2 3
4 5 6


More Tables Syntax

See this page for extensive info on the use of tables: Tables

Code

All the above examples of Wiki code where printed out by encapsulating them in a <nowiki></nowiki> pair.

By putting one or more spaces in front of each line lines are shown as:

 this

Another way to do this (for large portions of code for example), is to encapsulate them in a <pre></pre> pair.

Alternatively, if you don't need or want a big code box, you can use <code></code> which results in the following:

This is an example


Cross References

Cross references are done wikiwise, where as in previous docs we used labels to indicate an object. Wiki uses the object name; so what we need is a *unique* naming scheme for figures.


Webography

Wiki sites here


File Names

File names are a delicate matter inasmuch as they must be unique throughout all of the Blender Documentation Project and are self-explanatory to allow for cross references from one chapter to another etc.

It is thus higly advisable to stick to a given standard:

For Core documentation

 Manual/self-explanatory-name

For Images in Core documentation naming scheme is similar. But, sadly, '/' is not accepted by the system. So use '-' rather than '/'. For example:

 Manual-self-explanatory-name.ext

The user that is defined is completely up to the author and who is responsible for keeping the whole label unique.

Standardization of Words/Terms

Internet vs. internet? popup vs. pop-up?