TOOL THE DOCS

Free & OS tools for the writing, managing, testing and rendering of documentation
recap from devroom track at FOSDEM 2018

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.

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

see demo

Ferit's talk proposal outline

video recording from Fosdem



presentation slides

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

video recording from Fosdem



presentation slides



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?

  1. How would I test that?

  2. Write and run test as if it already existed. Test fails.

  3. 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




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

video recording from Fosdem



presentation slides

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

video recording from Fosdem



presentation slides



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:

  1. topics people want to read about, then

  2. 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



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



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.