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 technical 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.

3 comments 1,543 views
  1. 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!

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

  3. 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

  1. Leave a Reply

    Your email address will not be published. Required fields are marked *