Skip to main content

Documentation at balena

"Is documentation really important for this feature?" > "Are menus really important for a restaurant?" Docs are an integral part of our products.

They’re the single source of truth for our users. They educate how to get started, describe the functionality, inform about edge cases, and enable users to get the most value out of balena. Each feature on the roadmap has to have a plan behind how it's going to get documented.

This could be in the form of a new section, page, or paragraph in the docs. Docs can be further supplemented by tooltips on the dashboard, --help commands on the command line or even blogs. The documentation should be clear, easy to find, and ready to go when the feature is released. To say it clearly,

If it isn't documented, it hasn't been released.

Docs Process at balena​

TLDR: Everyone is required to contribute to docs.

Balena maintains a diverse set of products. Having a single documentarian or even a docs team in charge isn't effective. It's too much context for an individual and making changes authoritatively that are factually correct is very hard. Hence, we collectively encourage everyone to take ownership of documenting at balena.

At balena, documentation is equally as important as writing code. Hardware-related projects in IoT are notorious for their bad, incomprehensible documentation. At balena, we aim for a higher standard of developer experience for those using our products.

All this is possible by enabling product builders to document their own products. This way the person with the most context about the assignment is also the person documenting the project. We work on docs using one of two approaches:

  • Docs are maintained alongside the code to build the docs site (for example, balenaOS, balenaSDK, or Supervisor Docs)
  • Docs are generated by fetching docs from many maintained sources of truth (for example, balenaCloud Docs or masterclasses).

These help us streamline updates by combining changes to docs and code in the same pull request. We use Docusaurus v2 throughout balena using markdown to write docs. When a pull request is merged, the docs site is automatically updated using the Docusaurus Builder. The main purpose behind building this pipeline was to help balenistas focus on writing docs rather than maintaining the framework, features, and themes.

Who can contribute?​

Anyone. We welcome changes from everyone on the team. If you've found a spelling mistake, a link not loading correctly, or a clarification we can make to improve the docs, go right ahead and open a pull request (or submit an issue!). Updating the docs while working on support is a great opportunity to reduce friction for our users.

Opening a pull request to fix something right there and then is much more helpful than opening an issue. Since, it can take some time till the issue gets assigned, worked on, and eventually resolved.

Looking for help in contributing​

We have a lot of members on the team who would be willing to help you make a pull request.

If you have a PR that needs help, a review, or clarification then feel free to post your question on the help stream in Zulip with a @stream tag to ping everyone. Refer to our section on GitHub in tooling to learn more about how we keep our code versioned.

Questions are greatly appreciated and remember no question is silly.

Looking forward to seeing your contributions, balenista!