# Improving the Blender manual

So to follow up my previous post, the manual project chat room is live and ready for action!
Contributions of all shapes and sizes are welcome.

## How do I start?

If you're unfamiliar with the manual editing process, it essentially goes like this:

### Setup build environment

You'll only have to do this once. It's a bit of a complicated process if you're unfamiliar with version control, but setting things up now will vastly speed up your workflow in the future.

Feel free to ask any questions in the chat room.

### Pick something to fix

Right now problems are so plentiful you can probably find a good place to start just by looking at the manual, but there's always something on the tracker to pick from. To avoid conflicting work it may be a good idea to create and claim a task on phabricator, or at least check that no one else in the chat room is already working on the same thing.

When writing new sections from scratch be sure to check that the section doesn't already exist somewhere; in some places the docs are so disorganized that sections may not be where you think they are. If you find a "hidden" section like this which might be better placed elsewhere, create a task describing which files should go where and why.

Do note that many existing files in the manual don't follow the style guides since they were imported from the wiki, so be sure you base your writing off the official guide and not existing files.

### Write documentation

The manual is written in RST (reStructuredText) markup. The guide on the manual should explain most the the syntax you'll need to know, including some constructs specific to the blender manual.

Be sure to read the writing style guide and verify your documentation follows the guidelines.

The main purpose of the manual is to provide a consistent, reliable, and maintainable reference. Tutorial-like step by step instructions detailing how to do a particular task are not considered good material for the manual.

### Submit for review

To make sure the manual stays organized and maintains a good quality standard, submitted contributions are reviewed before putting them on the manual.

Create a diff and upload it to phabricator (developer.blender.org) for review:

1. Create an account on developer.blender.org if you don't have one already.
2. Create a revision by clicking the Submit Code button on the home page.
3. Once presented with the submission page, either upload your diff file or copy/paste it's content into the Raw Diff box. When finished, click Create Diff.
Review the diff phabricator sees to ensure it's correct, then click Continue.

4. You should now be presented with a form. Write a descriptive title and briefly describe the purpose of the patch and what it changes. Set the reviewer to Documentation. I also like to set the Repository and Project, but this is optional.

5. Developers or other documenters will review your submission to make sure it follows the guidelines and fits in with the rest of the manual. They may have a few suggestions, in which case you may find yourself wanting to update the revision with a new diff.

To update a revision, follow the same steps as above, but on step 3 select the revision you wish to update in the Attach To drop down:

Don't worry if this sounds complicated! As always, feel free to ask any questions in the chat room.

## I don't feel like writing documentation, but I want to help

Another way you can help is by finding problems with the manual and reporting them here. As always, it's a good idea to check that the problem hasn't been reported already.

# Contribute.rst

I was editing the timeline page to improve it, when I discovered while searching for a page to link to, that one, very good one, already existed. I ended up wasting a good deal of time. I have added this revision to warn future writers about thsis pitfall.

• Good catch, thanks. Sep 12 '15 at 1:02

# Re-organize "getting started" section

This shuffles a lot of pages out of /getting_started/basics which didn't really belong there.

# Standardize Game Engine Controllers

I moved all the standard parts of the game engine controller into one file.

I think there should be a better understanding and reorganization for the programming section of the blender manual. The problem I see for other BGE and BL users is that they go in and are scared to code in python. In-fact they are because there is no explanation on how to code in BGE and BL except for the fact that you need to go get a "Python Programming" book which is true, however, that book isn't about how python code will function in BGE and BL.

• This isn't really the proper place to hold a discussion on these sorts of things. The "official" places for documentation discussion is on the mailing list or IRC.
– gandalf3 Mod
Sep 23 '15 at 9:00
• You could also make a task on phabricator Sep 23 '15 at 17:10