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:
- Create an account on developer.blender.org if you don't have one already.
- Create a revision by clicking the Submit Code button on the home page.
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.
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.
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.
Resources
Links to useful places
- Writing style guide
- RST syntax reference
- The #blenderwiki IRC channel
- The Bf-docboard mailing list
- Talk at Bcon 2014 explaining the rational behind the switch from MediaWiki to Sphinx.
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.
