Meta:Guides/Writer Guide

    テンプレート:Meta:Guides/index

Note: this page is quite out of date:

• The manual is no longer maintained in the wiki, see: Project Page and the New Manual
• Currently the wiki is used mainly for developer documentation and user pages.

The page should be updated to reflect this.

---

Get a wiki account

Blender Wiki is limited to technical documentation for and by developers and those who want to help developers with design docs.

If you want an account, please contact developers via the bf-committers list or via IRC. Info is below.

https://wiki.blender.org/index.php/Dev:Doc/Contact

Writer Guide

Welcome

It's very easy to make simple changes to the contents of the Blender Manual wiki, and there is lots of help available (see above list). It only takes a few clicks. Just create a mediaWiki account then:

• Click the "Edit" page tab at the top of the page.
• Make changes to the text (using mediaWiki Help if required).
• Click the "Save page" button.

To help you with more complex edits (e.g. updating to describe latest Blender developments, filling missing pages, etc.), please read the Writer Guide below.

Happy writing!

Introduction

This document is intended to help writers, particularly new writers, to make improvements to the Blender User Manual as quickly and efficiently as possible.

All Blender users are welcome to help maintain the Blender User Manual. The User Manual is a large document (21 Sections with over 600 pages) and it needs constant maintenance. Users can help in two ways:

• by notifying the Admin Board of any problems;
• by updating pages to correct the problems.

In common with all other parts of Blender documentation, the Manual is written and maintained as a Wikimedia document. Each new version of Blender (2.49, 2.5, 2.6 etc.) has its own version of the manual.

Contacts

The Blender Foundation appoints a User Manual Admin Board who are responsible for the Blender User Manual. Writers can email the Admin Coordinator of the User Manual Admin Board.

Also there is a wider group of the Blender community interested in User Manual maintenance. These can by contacted using two methods:

• Mailing list: bf-docboard Our main way of distributing documents, discussing ideas, and keeping track of progress.(Registration required).
• IRC channel: #blenderwiki on irc.freenode.net. For meetings, informal discussions, etc. See Chat for further details about using IRC.

Editing Guidelines

The main purpose of wiki maintenance is to ensure that the content of each page provides the user with a clear, concise and up-to-date description of the Blender function in the current version. Over and above this, the page should conform with the User Manual context (see below) so that we keep a uniform User Manual layout.

Editing rights

You don’t need to ask for editing rights, since we use a Captcha system to verify that registration has been made by humans and not bots.

Just create a mediaWiki account and reply to the confirmation mail to get the right to edit wiki pages.

Mediawiki Editing and Other Facilities

Edits are made using the Mediawiki editing facilities. In addition, the wiki system incorporates a range of facilities for navigation, discussion, tracking and watching page changes, and other more advanced features.

The mediaWiki Help pages provide details and instructions for the mediaWiki facilities.

Style, templates and translations

• Follow the Blender wiki style guidelines.
• Use the Blender wiki templates for descriptions of wiki editing, facilities etc.
• If you are localizing the wiki, follow the Blender wiki internationalization guide.

Spelling and Grammar

• Where possible please use American spelling and grammar rules when editing and creating wiki content. So for example it is "color" not "colour", "organization" not "organisation".
• For API, Scripting and other programming language content, you should also follow the Americanized spelling rules where practical.

Icon Library

• It's a good idea to include buttons and icons when describing actions for users. See our icon library.

Blender Manual Structure

User Manual pages are laid out by means of a Naiad skin, which gives three panels:

• navigation (the wiki pagenames and structure)
• page content
• page structure (titles/subtitles).
  • [NB Only one or two of these columns may appear on low-resolution screens]

The contents of the Navigation column cannot be changed. The pagenames and structure for the current version of the Blender User Manual have been the subject of much debate, deliberation and compromise between the User Manual Admin Board and other Blender Community coordinators. Any changes have a lot of implications in the wider Blender documentation structure, search engine categorization etc.; see this wiki structure for more information. So please:

• Do update (i.e. edit, correct and improve) the content of existing pages;
• Do NOT update page titles
• Do NOT update page filenames.

If you wish to suggest changes in structure for future versions, please contact the Admin Coordinator in the first instance.

Updating Pages

Setting up to become a User Manual writer is simple. Just

• register on bf-docboard
• open a mediaWiki account (See Login/Create Account, top right corner of screen)

Then minor edits (grammar, corrections to comply with style guide) can be made directly by editing the wiki Manual page.

For major page edits, you can choose your method according to your confidence and experience.

EITHER:

• Go ahead and make your changes in the wiki Manual page. BUT ALSO, once you are satisfied with your corrections, please
  • email bf-docboard with subject "Re: Page Update" giving the category and filename(s) you have modified, so we can communicate if there are any issues with your changes.
  • add a brief note on the Discussion for the page saying what (and, if appropriate, why) you made the changes. Add a Signature and date to your discussion note.

OR

• Use your User Space to get a Review of your proposed changes before altering the real wiki Manual page. This can be done as follows (assuming the name you have chosen is XXXX):
  • Go to your user page and open edit mode (e.g. http://wiki.blender.org/index.php/User:XXXX)
  • Make a link to a new page with the appropriate address and save, e.g. Window types to correspond with http://wiki.blender.org/index.php/Doc:2.6/Manual/Interface/Window_types
  • The new link will display in red as there's nothing in the new page yet
  • Click the red link to open up edit mode for the new page
  • Open a new browser tab, open the wiki manual page that you want to fix, then go into edit mode
  • Copy and paste from the wiki manual page to the corresponding version on your user page and save your user page version
  • Add an InProgress template to the wiki page (so that people know someone is working on it) and save it
  • Now you can edit your user-page file to make your proposed changes.
  • When you're finished, email bf-docboard with subject "Re: Review Request" for a review by a more experienced writer (eg. an Admin Board member). They will work with you to polish the page if required, then help you to move it to replace the original wiki manual.
  • add a brief note on the Discussion for the page saying what (and, if appropriate, why) you made the changes. Add a Signature and date to your discussion note.

You may like to add the page to your Watchlist, and watch it, so that you follow any future changes to your edits.

Please note that, if your changes are not considered by the Board to improve the page, they may revert your changes. The Admin Board Coordinator has final decision on all matters of Blender Manual content.

Page Content Guide

The content of the Manual page describing a Blender facility (text, images, links, etc) should give sufficient detail of the current version of the facility to enable a new user to make full and effective use of the facility.

Titles, Sections and Headings

Titles, headings and sub-headings are enclosed using strings of = characters. The Page Structure panel of the page automatically updated to the structure and headings in the current page.

In addition, formatting such as bold/italic fonts, indented lists, bulleted lists etc. can be otained in the same way using strings of * and other characters (you can see these used by 'edit' on this page). See Help:Formatting for a complete description of the range of formatting options available.

Please note (again): do NOT change with main title of your page without very good reason (and consultation with the Admin Coordinator).

Page Text

The text should describe the feature as fully and succinctly as possible.

Check that the text gives a full description of:

• the purpose of the facility
• all the user controls (buttons, lists, check-boxes, etc)
• any special information required to use the facility.

Links

Links to another page in the wiki (internal links) are obtained by strings of the form

[[Main Page|different text]]

For other links, see Help:Links for a detailed explanation of the range of facilities available.

=== Images