In the tech world, we’ve all struggled with documentation scattered all over the place. In the open source world documentation is particularly important. Clear and well-organized documentation is essential for developers, contributors, and users to understand, contribute to, and effectively use a project.
In a recent project we tried to bring order to this chaos by moving our documentation to a static rendered website. Let’s dive into why we did it, the mess we came from, the simple solution we found, and the cool things we’re aiming for in the future.
Motivation: Getting Docs Closer to Code
Our main goal was to have our docs right there with the code. We wanted a format that anyone could easily modify, making it easy for team members, project developers and externals to contribute. Plus, having docs as part of version control and quality checks just seemed like a no-brainer.
We also wanted our docs to be presented in a way that didn’t scare people away - code in code blocks with syntax support, important stuff highlighted with admonitions, and all in one place.
Where We Started: The Doc Scavenger Hunt
Picture this: Essential information hidden away in endless Github README files, DOCX files, Google Docs, and Notion workspaces. Some were even trapped in unmodifiable PDFs. Visual styling was almost non-existent, making the docs look not very inviting.
Our Simple Solution: Static Docs on Github Pages
We decided to split the content (all in Markdown files next to our code) from the presentation layer. This is a quite common approach that various open source projects have adapted.
For the tooling for the presentation layer we experimented with MkDocs and Docusaurus. In the end we decided to move forward with Docusaurus because it has a slightly bigger community behind it (developed by Meta), runs on NodeJS (a slight bit easier for us), and it looks prettier to our eyes.
Our Lessons: Exploring the Static Wilderness
Comparing static website rendering frameworks was very insightful. Splitting docs into Markdown files felt like the most natural thing ever. For future projects, we’re planning to implement statically rendered documentation from day one.
Examples: Airlink and OpenSmartMeter Docs
We’ve already migrated Airlink Documentation and OpenSmartMeter documentation. Any comments, feedback and suggestions are more than welcome.
- OpenSmartMeter documentation | OpenSmartMeter (Docusaurus)
- https://airlinkdocs.enaccess.org/ (MkDocs)
Of course also updates to the documentation itself (which should hopefully be easy now) are much appreciated!
Outlook: What’s next?
First of all, migrating the documentation for all of our active projects to static rendered websites. Looking ahead, we’re dreaming of making our docs global with internationalization. And, we’re aiming to seamlessly integrate renders of PCBs and schematics, keeping everything up to date and snazzy.
Stay tuned for making docs less of a headache and more of a delight!