Accomplishments
Along with normal updates and improvements to the documentation, there have been several larger changes to improve docs.blender.org
-
SVN branching – To stay at the pace of Blender development we have set up version control branching to be able to update multiple documentation versions at once.
-
Build Server – Recently we migrated the old system set up years ago to compile the static web pages to a new build pipeline integrated with buildbot. This new system is faster, flexible, and easier to maintain.
-
Sphinx/Theme – Several fixes and improvements have been contributed upstream to improve both Sphinx and the website theme.
-
EPUB support – Added initial EPUB support allowing users to read the user manual on ebook readers.
-
Translations – Added several new languages.
-
Project Management: We now have nicely organized tasks to keep track of undocumented new features
-
Project Management – Added a convenient way to report issues in documentation.
Roadmap
One of the things we want to improve is making it easier to contribute to the Blender documentation projects. We have identified several issues that have been making it difficult for users to contribute.
One of these is knowing where exactly they can help. For the most part, our documentation is pretty good so it can be hard for new writers to know where effort is needed. This is one of the issues that will be solved by some of the goals listed below.
Another difficulty is the tools, Sphinx and Subversion are both rather technical which is hard for non-developer-minded people to use. Using Sphinx and version control software is still our desired tool as it still offers many benefits over the old wiki however we want to make using these tools easier.
Many other open-source projects use the above tools which have contributed to the large success of many projects hosted on https://readthedocs.org/ However, in some ways we are behind the methods that other projects take towards documentation. The tasks listed below related to the documentation tooling seek to solve these issues.
Short Term Goals
-
Improvements to the contributing guide.
We want to make this guide more helpful by for example including guides on how to document new features. We also want to make the overall guide simpler and less confusing.
-
Improve the project management tasks.
While we have tasks like https://developer.blender.org/T85053 we want to make them more welcoming and not a long list of commits. We want to allow non-technical users to be able to easily understand commit messages to understand how new features might work and where to find them in the UI and documentation.
-
Improve the visibility of project management tasks.
The tasks mentions in the last point can be difficult to find, we want to make these more discoverable to new contributors by linking to them from the contributor guide. We also will start adding the Good First Issue tag as these tasks have proved to be very helpful in attracting new users.
-
Improve the todo list
As an experiment, we started a todo list inside the documentation. Several improvements can be made here to point new writers to areas of the manual that could use some improvement.
-
Make better use of
sphinx-autobuild.This is an extension of Sphinx that will automatically compile and reload a webpage when a source file has been updated. Support of this has already been added however, we can improve on this by making it default
makecommand and add documentation.
Medium Term Goals
-
Blender ID support on developer.blender.org
A common complaint that we have heard is that is difficult/annoying to create a 2nd account for a Blender website. In the future, we want to make this a lot easier by allowing users to sign in with their Blender ID.
See this task for more information: https://developer.blender.org/T69300
-
Migrate from SVN to Git
SVN is a rather dated version control program with a limited user base and updates. We want to migrate to using Git which has more users and many simpler GUI clients than SVN does.
See this task for more information: https://developer.blender.org/T73394
-
Add a mirror on GitHub
Blender already has several mirrors on its official Github Account. This has been helpful for the deliverability of Blender’s source code and is something we would like to extend to the user manual.
-
Weblate
Weblate is a tool that allows easy online editing and management of Blender’s localization projects. This is a task that will improve both Blender and the User Manual see this task to learn more: https://developer.blender.org/T68588
Long Term Goals
-
Online editing.
This is one of the hardest issues to solve requiring some series work but also the biggest issue making it difficult for contributors. At some point, James will be looking into migrating from Phabricator to a custom Gitlab install. This will allow users to easily edit and submit a pull request all within a web browser without the need for Python or the command line. This will also allow contributors to maintain their own “forks” of the documentation which is useful when users want to make large changes to the documentation.
As an interim solution, users can edit online using the GitHub mirror however this is not a solution we want to officially support as it relies on the use of services outside the blender.org domain.
-
Participate in Google Season of Docs
Blender has participated in Google Summer of code for a while now but we want to expand this to participating in Google Season of Docs as well. This is a bit of a longer-term goal as it only comes around once a year and presents itself with some administration overhead (applications/mentors/etc…), we hope to participate next year in 2022.
Conclusion
If you have an idea related to how we can improve the current documentation process that is not listed above please reply to this post.