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:
  • Technical documentation goes to the Wiki (at least for now).
  • New Technical Documentation category on Devtalk, for feedback, discussions and meeting notes.
  • New Technical Documentation tag/project on developer.blender.org, to collect specific tasks to work on. Keep an eye on this if you’re not sure what to work on. Or add own tasks.
  • Other developers found live-editing platforms like HackMD useful for writing. Move the documents to the Wiki once ready!
• 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.