Meta:Guides/Style Guide

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

Please follow the Writer Guidelines and, in general, discuss with other authors when you plan big changes.

General Guidelines

Contents

• Be clear and concise
• Write idiomatic and correct English

Page structure

• Add headers and footers to each page to help reader to navigate the Manual|Tutorial|Reference
• Subdivide pages into chapters, sections and subsections
• For quick browsing, right after the title add an abstract to describe the topic, aims and contents, especially for long chapters
• If a topic is too long for a page, divide it into subpages

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.

Editing guidelines

Writing

• Official mediawiki doc: very well done and easy to read.
• The only notation about formatting wiki links is: please don't use literal fonts on links, they change aspect and it's more difficult to understand they're actually links.
• Templates guidelines: check the available templates and use them wherever you can, it saves reading time and helps maintenance (complete list of templates)
• Code guidelines: useful to insert python or C code excerpts
• Tables guidelines: useful to quickly show a range of data

Inserting files, images and media content

• Use the Upload file link in the 'Wiki' menu (in the footer, on the right) to upload content to wiki
• Images guidelines
• Media guidelines: add videos from Youtube and Vimeo
• Formulas guidelines: add formulas in our wiki using latex syntax.

Cross References

• Cross references are done wikiwise, so when linking a page (or a file or an image) put the name of the page you want to link in square brackets.
  
  Example:
  
  • The name of this page is "Meta:Guides/Style Guide",
  • [[Meta:Guides/Writer_Guide]]: returns Meta:Guides/Writer_Guide,
  • [[Meta:Guides/Writer_Guide|Writer's guidelines]]: returns Writer's guidelines.

• Don't use the complete url (http://wiki.blender.org/index.php/....) for BlenderWiki pages.