The Blender User Manual¶
Blender’s manual uses Sphinx, though they seemingly host it on their own infrastructure. It uses the Furo theme (like this manual), but kept the look mostly vanilla.
Sections¶
There are three main sections:
- Getting Started
About Blender, Installing Blender, Configuring Blender, and the Help System. Consists of stuff to make you start using Blender.
- Sections
The first three sections, User Interface, Editors and Scenes and Objects are introductions to the philosophies of the software.
The next sections are mostly divided into workflows (Modeling, Sculpting and Painting, Rendering, Motion Tracking and Masking, Video Editing, etc.) They each have one Introduction chapter. Every subsection in these sections also have introduction chapters.
Note
In this sense they’re more of a reference or a wiki, rather than hands-on tutorials. Which makes sense since it’s the user manual.
Also it’s surprising to know that even introductions themselves can have subsections and more subsections within, as seen in the introduction to the Sculpting section.
Starting from the section Assets, Files, & Data System, the sections are about documenting the internals, add-ons and quirks of Blender.
At the end it has a glossary and a index.
Note
One needs to look into how they generate index pages; this doesn’t seem to be offered by Sphinx.
- Get Involved
Documentation of how the manual is written, including style guides, commit guidelines, and translation instructions. Could be of use to us too.
Note
The whole section is a worthwile read. It goes into the very specifics on how some features should be documented (and provides templates for some of them), and how the manual should be written and maintained.
It seems like they also make use of in-house tools, directives and roles (e.g. the Blender icons) to alleviate part of the pain of writing and managing documentation.
Remarks¶
- Chapters
They seem to split stuff into subsections quite aggresively, at least from a layman’s point-of-view.
The chapters don’t really include examples or tutorials, they are just descriptions of the features. As a manual this kind-of makes sense, but like the interface, a newcoming person would probably also get lost in the manual. In any case this is interesting to know, and we’d need to shape a direction to make the manual maintainable like theirs.
- Labels
They don’t use
:guilabel:for some reason. They opt for italics instead.For mouse buttons they use
LMB,MMBandRMB. Understandable, but I guess there could be a better representation?For shortcut keys they use
-as the separation character. I’m used to+but I guess it’s just a personal preference (and the Sphinx role works either way).They have their own role
:bl-icon:for icons. I’ll have to look into how it’s implemented.They make smart use of
:toctree:’s in different documentation folders, since they are all compiled into the left menu. For folding up documentation they set the:maxdepthto 2, otherwise it is set to 1.
- Organization
They have their own version and language switcher.
The footer is modified to contain:
Copyright: added the license.
Shortened the theme attribution to “Made with Furo”.
Added a “Last updated” date.
Added 3 buttons: View Source, View Translation, and Report issue on this page.
Note
A minor UX issue on their part: the top-right “Edit this page” button needs login but the “View source” link doesn’t. They should be swapped.
It is an extremely large manual and I’m impressed by how well it seems to be maintained. It does feel like the F1 help manual of the old times, which is really nice.
One thing I hope they have is quickstart tutorials and examples, but there are no shortage of those in the Blender community, so it makes sense why they omitted it.