From BlenderWiki

Other pages about editing the wiki:

Todos list | Revision Process

Writer Guide | Notes for translators

---

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

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

[edit] 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 the Blender version to which the page is updated. This is done via

 {{UM/navigator|2.32}}

where of course 2.32 is the relevant version number.

It shows as

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:

 {{UM/foot|previouspage|followingpage}}

This shows as

Previous: Meta Manual index Next: Meta

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

[edit] Templates

There is 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

Lets just insist on the {{Literal|}} one, which should be used to ‘wrap’ all reference to GUI items (control name, menu item, …).

[edit] 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:

It saves you and your readers time if you 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!

[edit] Typography

It might be useful to add common English typography rules, and perhaps a link to a reference site about this subject… As I did in the french version of this page. --Mont29 14:21, 18 February 2009 (UTC)

[edit] Images Guideline

The utilisation 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.

[edit] Floating Images

Floating 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, described here.

The usage of unreferenced images is discouraged. If you have an image that 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 comfortable reading on a web browser.

The most prominent feature of Blender’s interface is that it’s fully OpenGL rendered and scalable. This is great but will sadly result in many non-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 and 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.

[edit] 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. Use the set kindly provided by DocBoard.

[edit] Inline Smileys etc

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

[edit] 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.

[edit] 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.

[edit] Documentation Style in Practice

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

[edit] Image Examples

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

[edit] 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]]

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

[edit] Floating Images

This one is a bit more tricky, since you have to take into account the fact that it 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}}

[edit] Inline Images

Inline images like are even easier to obtain:

[[Image:DemoImage2.png]]

[edit] 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.

[edit] More Help on Images

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

[edit] Tables

Tables can be written either in HTML or by using the 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

[edit] More Tables Syntax

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

[edit] Code

All the above examples of Wiki code were 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

[edit] Cross References

Cross references are done wikiwise, where 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.

[edit] File Names

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

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

For Core documentation

 Manual/self-explanatory-name

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

 Manual-self-explanatory-name.ext

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

[edit] See also

Custom Blender Tags