17
$\begingroup$

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

Install SVN and Sphinx.

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.

    enter image description here

  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.

    enter image description here

  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:

    enter image description here

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.

Resources

Links to useful places

Show off your contributions!

Once you have added a new contribution, please add a link to the diff page here as an answer. It will encourage others and give an opportunity to receive feedback.
But please try to keep review comments/feedback on phabricator.

$\endgroup$
4
$\begingroup$

Clean up glossary

$\endgroup$
3
$\begingroup$

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.

$\endgroup$
  • $\begingroup$ Good catch, thanks. $\endgroup$ – iKlsR Sep 12 '15 at 1:02
3
$\begingroup$

Re-organize "getting started" section

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

$\endgroup$
3
$\begingroup$

Standardize Game Engine Controllers

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

$\endgroup$
1
$\begingroup$

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.

$\endgroup$
  • 2
    $\begingroup$ 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. $\endgroup$ – gandalf3 Sep 23 '15 at 9:00
  • $\begingroup$ You could also make a task on phabricator $\endgroup$ – GiantCowFilms Sep 23 '15 at 17:10

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .