Meta/Style Guide
Wikipedia，自由的百科全书
To maintain consistency throughout all Blender Documentation, perspective 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
Contents |
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
{{UM/navigator|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
{{UM/foot|previouspage|followingpage}}
Showing like
|
previouspage and followingpage should of course be valid links to proper pages!
Templates
There are a limited set of templates defined by the docboard. You are kindly requested to use them and only them.
Template listing is here Templates
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 4.4.
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:
Floating Images
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 
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.]]
|}
 |  |  |
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
| × | 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/Part##/self-explanatory-name
Part## is Part ##, with ## being the roman numeral of the part the object belongs to. The pages name themselves are a good example for this.
For Images in Core documentation naming scheme is similar. But, sadly, '/' is not accepted by the system. So use '-' rather than '/'. For example:
Manual-PartXX-self-explanatory-name
The user that is defined is completely up to the author and who is responsible for keeping the whole label unique.
