TOOL THE DOCS
This year, a long time dream came true when we finally got a tech writers' DevRoom accepted at FOSDEM, co-organized by Chris Ward and Kristof Van Tomme. Yay! A big shout-out to the organizers of the conference and thank you for the presenters! With great pleasure we share with you the recordings, slide decks and Laura's notes from Tool The Docs.
A developer track for documentarians at FOSDEM 2018, dedicated to free and open source tools for the writing, managing, testing and rendering of documentation.
- Ferit Topcu: Automating style guide documentation
- Stefan Knorr: DocBook Documentation at SUSE
- Honza Javorek: Test your API docs!
- Kitti Radovics: Docs like code in Drupal
- Stephen Finucane: A lion, a head, and a dash of YAML
- Shaun McCance: Mallard, Pintail, and other duck topics
- Jessica Parsons: Finding a home for docs
Automating style guide documentation
How we at Zalando Retail Dept automated our Styleguide & source code and reduced the gap for contribution
Ferit Topcu
Front-end Software Engineer, Zalando SE
Enable developers to create docs to a new feature asap, without switching context.
As soon as a new feature is developed, instant testing against styleguide via inhouse styleguide app. Stylelint (scss, css): ensure code consistency accross many developers and UX. For each pull request they test build again and also lint style.
Development in components - document in components
Use JSDocs
documentationjs an OS library, generate Markdown from your JS docs (part of CI)
automated html output.
Document all properties of a component, give an @example for how to use that feature.
See demo project
Docs part of Definition Of Done
Pull request only accepted with documentation had to be centrally decided and enforced policy pro: easy onboarding
Low entry level for documentation
Markdown and GitHub knowledge is sufficient for a start.
JAMstack approach
Ferit's talk proposal outline
video recording from Fosdem
presentation slides
"Documentation is as important as code" @FokusMan #FOSDEM #TooltheDocs #writethedocs pic.twitter.com/PXsZ148Opx
— Kristof Van Tomme (@kvantomme) February 4, 2018
DocBook Documentation at SUSE
Automatically Ensuring Quality of SUSE Documentation
Stefan Knorr
Technical Writer at OpenSUSE Documentation Team
Workflow
Almost only docbook output. Accept input in many formats. Single-sourcing, multiple docs, multiple formats. Git+GitHub+GitFlow model+PRs+reviews. The gitflow branching model helps them keep track of the branches. OBS builds documentation RPM packages (OS toolchain necessary)
DAPS
Solved the toolchain gaps they found with upstream DocBook (publishing gaps too). Editor agnostic, they use many different editors. 1. profiling stylesheets, then 2. output stylesheets. Does not handle translation, outsourced.
They use their own RelaxNG schema (DocBook 5.1) DAPS validate
Styleguide:
language & structure rules (avoid confusing readers and translation costs):
synonyms, eg. use keycap to highlight keys, and change hit to press
"soft" syntax rules (not to crash validation) eg. avoid wordy phrases, avoid lonely sections
Their style-checker produces quite some output, with some false positives, this is not ideal.
Future plans:
Improve spell check, source lines (hard problem)
need both html and plain txt output but the xml format does not translate well.
Travis CI:
Publish docs to GitHub pages. ToDo: Integrate a style-checker without inundating people with error messages.
Stylesheet checks
DAPScompare, their own DocBook validation sheet. Future plan: need more example docs.
PS: xxlt is only well documented in German.
Stefan's talk proposal outline
Test your API docs!
It's tested or it's broken
Honza Javorek
Maintainer of the API testing tool DREDD at @apiaryio
Every interface is Human User Interface
In the end humans need to leverage the interface, so consider and develop every interface as UI. How to design good UI? Eat you own dogfood. How to position yourself as your future user? Use Test Drive Development.
Behaviour Driven Development
Cucumber/Gherkin Makes what you create testable 1. How should it work?
How would I test that?
Write and run test as if it already existed. Test fails.
Implement until it fits the original design. You fullfilled your original promise.
REQUEST library, see Kenneth Reiz's essay "How I develop things and why"
Readme Driven Development: Responsive API design
"...instead of engineering something that will only get the job done, you start to interact with the problem itself and build an interface that reacts to it."
"With Readme Driven Development, by the time you are done, the docs are already there."
Doctest: parse and run the examples, they have to run and succeed as in the readme. This ensures sync between code (implementation) and readme (essential contract with your users).
DREDD
Human and machine readable API.md.
DREDD works as doctest does for code.
Extend testing with hooks, most are contributed, you are welcome to add your own language into the open library.
Honza's talk proposal outline
video recording from Fosdem
presentation slides
"Design first. Docs first." @honzajavorek #FOSDEM #ToolTheDocs pic.twitter.com/ufsUjF7Ec4
— Shaun McCance (@shaunm) February 4, 2018
Docs like code in Drupal
Introducing Open DevPortal, an open source CMS based documentation tool
Kitti Radovics
Front-end Developer at Pronovix
What is docs like code
In Docs like code, a team uses version control systems (like GitHub) to collaborate on documentation inside a code repository.
Changes to the docs are then automatically deployed using CI/CD and static site generators.
Advantages of docs like code
Keep pace with code changes
Collaborate with the contributors of the documentation
Anyone can contribute (Technical Writers, Developers)
When to use a CMS for docs like code
- When regenerating the whole site for each edit is too slow (e.g. lots of content, or lots of updates and writers)
- When you need other content than just docs (landing page, marketing, blog)
- When you want built-in search (keywords, tags, categories)
- When you need Role Based Access Control (internal & partner APIs)
- When you want interactive documentation that talks with the API
- When you need rich interactions for gamification
After the introduction Docs like code in Drupal, Kitti explained how she is working with her team on a Drupal based solution that can import Markdown and Open API specifications from GitHub.
Upstream docs
How a CMS could be used to integrate documentation from different repositories, while maintaining a consistent UI for readers and for casual contributors.
Kitti's talk proposal outline
A lion, a head, and a dash of YAML
Extending Sphinx to automate your documentation
Stephen Finucane
Software Engineer at Redhat
Intro
reStructuredText - syntax (write) Docutils - parsing (write, individual files) Sphinx - build, multiple cross-referenced files
Sphinx extensions
Roles & Directives in Docutils
Example for roles: recurring format defined in docutils as a role, eg. GitHub issue number becomes a hyperlink in http output.
Create directive in docutils, eg. connecting to the GitHub API, import information on that GitHub issue when it appears in the docs.
Events in Sphinx
(not in Docutils)
Sphinx contrib, hundreds of extensions, you can use those the contrib ones mixed with your own.
Stephen's talk proposal outline
Mallard, Pintail, and other duck topics
topic-oriented help at the GNOME project
Shaun McCance
GNOME Developer, Writer, and Community Advocate. Runs the Open Help Conference & Sprints. Upstream documentation projects at RedHat Open Source and Standards department.
Mallard
Think about your docs differently:
topics people want to read about, then
build the docs bottom up.
Create a linking structure, where the links work both ways.
Can embed existing standards, vocabularies. Eg. its standard for xml translations.
Gives you a data model of your content.
The only problem with xml is that it's xml...
Need a lightweight syntax that has the possibilities of xml: ducktype.
Ducktype
Similar to Markdown or reStructuredText.
All the mallard-critical metadata are possible.
Allows nested notes, works completely with indentation, no limit to indentations.
Conditionals are still complicated but possible and easier to read than xml.
Anything xml does without its complicated syntax.
Can make use of all the xml tools e.g. validation.
Pintail
Supports Markdown and AsciiDoc but it's Mallard first.
A documentation publishing tool in the Mallard ecosystem.
Yelp.io
Config file: how to build the output.
Can mix documentation formats.
Search
Important to have context. Good first start to restrain search domain to the project where you are.
Allow to change search domain for user (e.g. dropdown).
Shaun's talk proposal outline
video recording from Fosdem
Topic oriented documentation with Mallard by @shaunm - live demo! #FOSDEM #TooltheDocs #writethedocs pic.twitter.com/DWThOqxnGl
— Kristof Van Tomme (@kvantomme) February 4, 2018
Finding a home for docs
How to choose the right "path" for documentation in open source projects
Jessica Parsons
Documentation Engineer at Netlify
Finding a home for the NetlifyCMS docs
Started with a readme on GitHub, like most projects...
Needed a website for all the docs: copied docs from GitHub to website (with Hugo), this resulted in two sources of truth.
Markdown magic: comments inside your files, pull them into .md files. Use it for taking from code repo to website repo, they took out the docs from GitHub. Problem with CI/CD, it broke the deploy previews.
Issue 750, 2017/okt/27: "Publishing docs in two places is no fun."
Want the ease of changing docs just as code changes go. Back to GitHub.
Docs edits in the same pull request.
Tag code releases and tag doc releases: you see the previous code with the matching docs (if you did publish your docs with the code).
Jessica's talk proposal outline
video recording from Fosdem
presentation slides
"Docs can get ahead of code." @VeryThorough has awesome, enviable problems. #FOSDEM #ToolTheDocs pic.twitter.com/xxCzxseL9U
— Shaun McCance (@shaunm) February 4, 2018
Original recordings at Fosdem, licensed under the Creative Commons Attribution 2.0 Belgium Licence.
To view a copy of this licence, visit http://creativecommons.org/licenses/by/2.0/be/deed.en
or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.