Participants: Bastien Montagne, Jeroen Bakker, Julian Eisel, Sybren Stüvel This was a spontaneous discussion, not planned.
We want to improve technical documentation, because we see this as critical for Blender’s long term health.
In daily work technical documentation is too often neglected. Whatever we do now doesn’t seem to work great.
Writing technical documentation can be hard and time consuming. Doing it together may be much more efficient and effective than doing it alone.
Let’s further explore where we want to go with technical documentation: Can we kick off a cultural shift to make the situation better permanently? What are the limits of current platforms? What other options do we have? How do other projects handle this? …
Technical Docs Day
Idea is to have some kind of regular “technical docs day”. More loose approaches tend to not work in our experience.
Pair documenting:
One developer brings the expert perspective (e.g. the person who implemented the feature), the other the outsider perspective (somebody who wants to learn about the feature).
Two (or more?) developers pair up and review/improve existing documentation, or write entirely new documentation.
For the first day, we will focus on an in-person effort to get started. For further editions we can look into involving more people remotely.
Of course others are free to do this as well (we’d love to hear about this!), but in the HQ we will focus on an in-person experiment.
Friday, Nov 25!
Some kind of meeting notes will be shared.
Further Discussion
Idea: Blender Developer Handbook
Frame the development documentation as a single “handbook”, to address current scattering of information.
From general documentation (building Blender, commit right setup, new developer advice, folder structure) over Blender design basics (Main & ID basics, DNA basics, RNA basics, UI architecture, …) to more detailed documentation (library overrides, BMesh, Alembic, …)
Open Q: How much of the technical documentation would this include? Everything? Only conceptual introductions with links to detailed documents?
Let’s have a glossary for precise technical terminology.
Let’s figure out some consistent structure & style for documentation pages.
Do we want to look into alternatives to the Wiki? None of us likes it much, or thinks that it is working well. But better to first focus on adding & improving content, a different platform can still be investigated.
Topics
Short list of topics for ourselves we came up with for the initial technical docs days:
Friday, Nov 25:
Library Overrides - Pair review: Bastien & Sybren
Asset System - Pair review: Jeroen & Julian
Asset Indexing - (New documentation) Jeroen & Julian
This might actually become a centralised “Blender glossary”, with some way to distinguish/filter between “artist/friendly” and “developer/technical” terminology.
But trying to fit the entire wiki into some linear handbook format, I’m not sure that’s going to make finding information easier.
The manual already has a glossary for artists, I think we are only concerned with developer docs here? Trying to unify those things seems complicated.
And besides a glossary, just making words into links to the relevant wiki page can help. Because I guess for most terms in the glossary you probably want the larger context and not a one or two line description.
I somewhat like markdown files right in the code repository for being able to commit docs along with code, but images are not ideal then, maybe with Git LFS it would be better.
But in general, switching to something else is going to take a lot of time that we can better spend actually writing docs.
Not sure i agree there, i vividly remember being asked to transfer some documentation i wrote locally with mark up/down/whatever to the wiki, transferring the content i had to something that looked ok on the wiki took longer than actually writing the content in the first place.
Short term you’re likely right, longer term, I’m convinced dropping the wiki for a system similar to the manual would be a productivity boost for everyone involved.
Yeah we also discussed markdown as a possible alternative that people are well familiar with. Personally I’d prefer this a lot to what we have now.
For example, Microsoft does a bunch of Markdown + Git LFS documentation, e.g. for Visual Studio Code (documentation repository).
I have to agree with @LazyDodo here. I spend a non-insignificant amount of time fighting with the Wiki with something that I know I can do easily in Markdown. It’s just better at making things look good by default. Plus, I think a decent amount of time can be saved by not having to reformat when moving things from Phabricator (or Gitea), devtalk or HackMD. (Which are just more convenient to work with and I think sometimes we write stuff there that should really be in the Wiki.)
Even besides the time discussion - to me other platforms just offer a much better experience, with better navigation, layouting, tooling (e.g. Markdown extensions, Git workflow, code review, WYSIWYG editors, …), source code integration, etc. So I’d argue this is a good investment. Although there’s the question of how much we want to move (e.g. are we gonna keep the wiki for personal pages?).
I like the idea of a Blender Developer Handbook in style to the user manual we have. Having a more structured / linear representation of the documentation we have in the wiki would be a nice improvement. While it might not work for all kinds of docs, it can work well for the onboarding and process docs for example, giving beginners more confidence in what to read first.
For this to work well, a web based editing possibility (planned with Gitea) is needed though. The wiki isn’t ideal, but edits there are faster than on the manual at the moment.
I think a “developer handbook” is still a good idea, and also a good reference frame to use when writing docs. Everything being digital means that we don’t have to make it “book-style linear” though. For example, there could be a way to choose your platform of choice, and you’d only see documentation for the platform of interest.