How do you document your project? What tools do you use?
Tool The Docs was for the second year now a DevRoom at FOSDEM, co-organized by Chris Ward, Mark Meyer and Kristof Van Tomme. The track is a great opportunity for project leads, documentarians, and other documentation enthusiasts from across open source projects to come together and talk about tooling that makes contribution to docs efforts easier.
A big shout-out to the organizers of the Fosdem conference and Thank You for the presenters! With great pleasure we share with you the recordings, slide decks and notes from Tool The Docs.
Developer Advocate at Nexmo
Describe APIs in both human and machine readable way with OpenAPI Specification. Allows you to separate source content and the output format: once you have the description, you can render any way you like.
Design first, with all stakeholders. Consider:
Using OpenAPI spec is an investment. It is a standard format that is picking up, you will be able to automatically generate more and more of it.
"OpenAPI Spec is not complicated, but it is a little bit unwieldy, and it is verbose."
If you have an API with lots of endpoints, use tags for discoverability. Tagging is freestyle and you can attach multiple tags to one path.
Feedback about on our documentation team experience
Developer at Pegasys
"Good documentation is one of the ways to achieve appreciation of your product's excellence."
Etherium blockchain is so complex, docs team needed an exploration plan like old-time adventurers: gather data, share findings and put these findings into the first basic version of the documentation.
First version of docs was a GitHub wiki.
Pros: out of the box wiki, table of contents, role-based-access-control.
Cons: for restructuring, they had to migrate the docs.
To be able to choose the right documentation tool, they list the requirements in order:
In Github and Jira they use tags to separate the pure code PRs and docs PRs.
Advice: gather accurate data, map it, report, and you can plan the next steps well.
The kubernetes.io stack, how we got there, and what it took to get there
Lead technical writer at Linux Foundation
Technical pivot achieved: Kubernetes docs natively support multilingual documentation.
Q1: How to publish multilingual content using Jekyll as a static site generator?
Q2: How to approve PRs for languages the docs SIG (Kubernetes special interest group) doesn't read, eg. Korean.
A1: Changed from Jekyll to Hugo: better multilingual support and shorter build times on large volume. Reduced technical debt.
A2: Kubernetes project's custom CI called prow allowed
Branching strategy: current+4. On Netlify these branches (plus dev) each have their own deployment -- version selector gives you a separate deployment.
Different aspects of Continuous Integration Testing for documentation testing
DocOps Engineer at Pronovix
Writing can be hard and Continuous Integration isn't easy either.
Automated testing can only take you so far: quality assurance starts in your own text editor, with the right settings for both.
There is no golden solution.
Well written and maintained documentation should be part of your internal and public company culture.
The docs' source code should also be standardized and easy to read: quicker edits, faster deploys. Write meaningful and readable documentation.
Editor Tip: Stricter testing rules on your local, if they passes, they will pass on the CI/CD linter settings too.
Two short demos: Basic examples for using Travis, using CI locally.
Q1: What if legacy docs were written without rules? A: Can only change them little by little, do not expect to work magic on 100% right now.
Q2: How to test code examples that are in a docs environment? A: Test code examples in a code repository and only then pull them into the docs.
Untangling complexities of the LibreOffice Help
Documentation coordinator at The Document Foundation
The gap between help documentation and new features is widening as development speeds up: contributed docs, immense localization effort.
LibreOffice is a large, interdependent program, teams working on translations into 100 languages: changes are risky, errors in docs have a large ripple effect.
They are developing a new toolchain, audience suggested looking into possible cooperation with Open Dita.
An exploration of the parsers and builders of the Sphinx documentation tool
Senior software engineer at RedHat
Who needs pandoc when you have Sphinx? An exploration of the parsers and builders of the Sphinx documentation tool.
How does Docutils work?
Docutils in itself provides some tooling which can help to understand what actually happens under the hood
Readers (reads from source and passes to the parser)
What about Sphinx?
How we migrated from a Wiki to the open-source Grav CMS
Team Lead, Documentation and Developer Experience at Adyen
"But the tools will also define your processes, that will have an effect on your organization."
Five years ago all docs in pdf: hard to maintain, distribute, analyze.
Changed to Confluence. Limitations: versioning, database is a black box.
Something may have worked well in a previous stage but now it doesn't, (e.g. now we need to automate).
Docs as code: existing models, could implement it but the collaboration, contribution and extensibility would suffer (Markdown, git).
If you implement a docs as code toolchain, you will mostly get feedback and contribution from developers, from other roles it will be minimal. This can have a long-term effect on your documentation's quality.
Try docs-as-code coupled with a CMS: Adyen implemented this with the OS Grav CMS. They have 5k pages of docs, this setup works well for them.