Technical Documentation Day

Friday, January 27, will be the first all-hands-on-deck technical documentation day. Developers, technical writers and other contributors are invited to spend a day on improving the developer documentation. It’s not just about writing some pages; it’s about learning how to write good technical documentation, making the process more enjoyable, and whatever else that contributes to a great technical documentation writing culture.

The plan is to make this a regular event, repeated once or even twice a month for a while.

Why?

Technical documentation is important for the long term sustainability of projects like Blender. Knowledge about designs needs to be shared better, so more people can make good decisions. It reduces reliance on core developers, helps avoid conflicts, misunderstandings and a good amount of bugs. And it should lower the barrier to entry for Blender development.

The technical documentation for Blender is lacking quite clearly – many parts of the design are missing documentation entirely even. It just hasn’t found its way into our daily processes. Decent technical writing is difficult, takes a lot of time & energy and may not feel immediately rewarding. It doesn’t have to be that way. But something tangible is needed to initiate change.

Join

If you are a developer, technical writer, technical artist or some other stakeholder who wants to participate, here’s the basic info:

  • Do whatever you think contributes to improving technical documentation.
  • However, communicate what you want to work on. Others may plan to work on the same thing.
  • Recommended: Read Google’s courses on technical writing. They will make you write better docs.
  • You’ll find plenty of things to document and improve here: https://wiki.blender.org/wiki/Source.
  • Platforms:
  • Guidelines, templates and examples would be useful. Help is welcome, see T102958.
  • There will be a video meeting for general discussion. See below.

Recommended: Pair Documenting

Some Blender developers experimented with documenting in pairs, and found it very useful. Basic idea: One person with knowledge about the area in question prepares a draft. Another person with little knowledge about it joins for a review, pointing out which parts are unclear or can be improved. Together they can turn the draft into a polished and well understandable piece.

A platform for collaborative editing is recommended, such as HackMD. Do not keep the documentation there, move it to the Wiki!

Let’s Meet

There will be a video meeting that day to discuss technical documentation topics. Here we can discuss things like, how technical documentation is handled in other organizations (e.g. using docs as code). But also things like tooling, auto-generated API reference documentation (Doxygen), higher-level structuring, etc.

The meeting will be limited to one hour. Meeting time and link will be shared on bf-committers and in the #blender-coders chat.

Support the Future of Blender

Donate and support Blender Foundation to work on core Blender development.

10 comments
  1. its a great thing

  2. I would appreciate in the docs to get use cases, files to download of for instance geometry nodes every new node instead of just explanation of what they do. A practical usage better than only pure docs.
    Links to featured videos more …
    That would be nice
    Thanks for the efforts for artists without “math” knowledge.

    • The technical documentation day is about developer documentation. Technical core designs, code architecture, development setups, maintenance notes and such, not user level documentation. Maybe the blog post should be more clear about that.

      • Ah OK, so my comment is not placed where it should be…so please where to ask for this topic ? Is there a plan for such help manual enhancement in the future ?
        Thanks.

  3. Ever heard of (La)TeX, NoWEB, Literate Programming ?
    Am using these since more than two decades to document my own programming efforts when working with the bash, Java, LOGO , Perl etc.
    Would be willing & glad to share my knowledge with anyone interested.
    NoWEB is a great tool to incorporate ALL the different languages in BLENDER in one single document from which its sources may be extracted automatically to buld different executables using the classical MAKE of *nix.

    Cheers from Wolfram

  4. Now that the “Phabricator to Gitea migration” is rolling out, I hope that the next efforts will be towards a simpler Translation system, such as Weblate. I am longing for Weblate to be implemented because for the moment, a “wannabe translator” has to know the rst syntax and SVN, which may refrain some people to contribute.

    https://developer.blender.org/T68588

    • The technical documentation day is about developer documentation. Technical core designs, code architecture, development setups, maintenance notes and such, not user level documentation. Maybe the blog post should be more clear about that.

      I don’t think translating the technical documentation is feasible or even worth it for now.

  5. I agree that the documentation needs to be changed and updated. When I started with the basics, some explanations or notes to the functions were incomprehensible to me, but in fact, in general, everything is not so bad, the documentation helps a lot in mastering, because there are no tutorials that could focus their attention on a topic that is individual for everyone, I would like to note that it would not be it’s bad to make more images with examples, the visual simplifies everything in twofold! I studied the documentation for a very long time, it is very voluminous, while I understood what work was done on it and how much time was spent on it, it’s nice to understand that in the future the documentation will only get better!

  6. Nice information, want to be part of this team to enhance my skills on technical writing.

  7. I think this is a really great initiative – these thankless tasks which are not exciting or flashy, which will not feature on an AskNK video or be a “killer feature” are what make or break a software in the long run.
    Hats off to everyone who works on this and really solidifies the foundation of Blender!

    Cheers and heartfelt thanks,
    Jonathan

In order to prevent spam, comments are closed 15 days after the post is published.
Feel free to continue the conversation on the forums.