TechDocsCon at Open Source Summit Europe
I recently attended Open Source Summit Europe 2024. It’s an event organized by the Linux Foundation, and although the main focus is on the development of open-source software, there was a good deal of documentation-related presentations and discussion.
It was also the first TechDocsCon track at Open Source Summit Europe, and I was really happy to see a micro-conference dedicated to documentation at such a big and well-attended event.
Main conference
Before going into the details of TechDocsCon, here are some documentation-related highlights from the main conference.
Linux Kernel documentation
One of the first sessions I attended was a Linux Kernel developer roundtable featuring Jonathan Corbet editor of LWN.net and the maintainer of Linux Kernel documentation. His talk emphasized the importance of clear and updated documentation in open-source projects. He pointed to a great reference: the documentation contributing guide for the Kernel. I was amazed that such a critical part of the Linux operating system only has one full time maintainer!
Also at the roundtable was from Alice Ryhl from Google, who discussed Rust documentation. She emphasized that if a developer encounters something undocumented, they should document it — framing missing documentation as a bug to be fixed. This perspective resonates strongly with the docs as code philosophy.
Innersource: best practices for internal open source
A panel session on Innersource covered how companies are applying open-source collaboration methods internally. Russell Rutledge from the InnerSource Commons Foundation spoke about the challenges and benefits of Innersource adoption. A key takeaway was the need for strong governance models, clear ownership roles, and champions within an organization to drive Innersource initiatives forward.
Useful resources from this panel:
Planning for software end-of-life and end-of-support
Another interesting talk from the main conference was centered around how to handle software reaching its End-of-Life (EOL) or End-of-Support (EOS) stages. The distinction between these terms was explored — whether it refers to the end of software maintenance, hardware support, or security updates.
The OpenEoX project aims to standardize the way organizations communicate these transitions in a machine-readable format, providing a clear framework for managing software lifecycles. Additionally, endoflife.date is a useful resource for tracking EOL dates across various software projects.
TechDocsCon track
Here are some highlights from the TechDocsCon track.
Next-Gen Documentation with AI - Hema Veeradhi, Red Hat
AI in general, but also in documentation, was a hot topic throughout the conference. Hema Veeradhi’s talk on using AI to assist with real-time help systems, automated documentation updates, and consistency checking across languages was really interesting. Some key highlights included:
- The different approaches to AI-assisted documentation:
- Proprietary live AI models (e.g., ChatGPT)
- Local AI models (e.g., Ollama)
- Self-managed/on-prem AI (e.g., RedHat OpenShift AI)
- Human-in-the-loop AI workflows: AI can generate initial drafts, but human review remains critical.
- Tools like LangChain and Argilla for fine-tuning AI-assisted documentation workflows.
Documentation Templates: A Helpful Aid or an Obstacle - Lana Novikova, JetBrains
Lana Novikova’s talk explored the role of templates in technical writing, highlighting their ability to enhance consistency, efficiency, and knowledge sharing. Drawing from The Good Docs Project (of which I am also a member) and the 2023 Open Source Maintainers Report, she noted that many open-source projects struggle with documentation, especially when reliant on volunteers. Templates act like design patterns in software, providing structured solutions that streamline documentation, reduce errors, and preserve institutional knowledge.
However, Lana cautioned against potential pitfalls, such as over-reliance, which may stifle creativity, lack of flexibility, which can make templates feel rigid, and misuse, where templates designed for internal documents are mistakenly used externally. To maximize effectiveness, she recommended using templates as a starting point, customizing them for different contexts, and continuously adapting them for improvement. She also discussed the cognitive science behind templates, emphasizing that structured prompts reduce cognitive load by tapping into semantic memory, making information more accessible. Ultimately, templates should serve as guides, not constraints, ensuring they support rather than hinder the documentation process.
Tackling Language Barriers in Open Source Docs: A Case Study of openEuler’s docs localization - Helen Liu & Wang Jing
With a growing developer community in Asia, documentation localization was a significant interest to openEuler. Some key challenges include:
- Keeping translated docs synchronized with the source.
- Addressing SEO and discoverability in multiple languages.
- Automating parts of the translation workflow using AI.
The openEuler G11N SIG is working on streamlining these processes, and their insights are highly valuable.
Learning by Example: Highlights from Google Season of Docs - Erin McKean, Google
As a previous participant, I found Erin’s talk to be a super interesting one.
Google’s Season of Docs program has highlighted how well-written documentation reduces support requests while increasing adoption. The main takeaway: investing in good docs pays off by making software more accessible and user-friendly.
Online Hands-on Tech Docs, the Easy Way! - Jorge Morales Pou, Broadcom
Another fascinating topic was explained in Jorge Morales Pou’s talk about using sandboxes for documentation training and hands-on learning. A sandbox is a controlled environment where users can interact with software safely. Some challenges and best practices discussed included:
- Ensuring a secure setup to prevent abuse (e.g., crypto mining exploits).
- Providing a way to reset environments automatically after a set time.
- Integrating databases as part of sandbox environments.
For those interested, VMware Tanzu Labs’ Educates Training Platform is an excellent resource for looking into setting up training sandboxes.
Final note
UX-driven documentation improvement
Although not at this conference, Lana Novikova told me about a talk at a previous Nordic TechKomm event by Dr. Oliver Friese from B/S/H Group, discussing a study on UX-driven improvements in installation guides. The research involved:
- Setting up a testing area in a lab.
- Observing how users interacted with instructions to install dishwashers.
- Creating “heatmaps” to pinpoint problem areas in documentation.
- Running workshops and using dot-voting to determine improvements.
The results led to significantly improved instructions, reducing customer frustration. This approach could be applied to many areas of technical documentation.
More about this research: Nordic TechKomm 2023 field notes.
Final thoughts
I thought that TechDocsCon at Open Source Summit Europe was a highly valuable event for anyone interested in documentation. It was great to see a dedicated track for documentation within such a large open-source conference, and I hope it continues to grow in future editions.
The call for papers is already open for the 2025 edition in Amsterdam!