@LukasRosenstock @kvantomme @APItheDocs @pronovix Glad that you had that experience. They need to do something about their messaging.
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.
How we at Zalando Retail Dept automated our Styleguide & source code and reduced the gap for contribution
Front-end Software Engineer, Zalando SE
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.
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
Pull request only accepted with documentation had to be centrally decided and enforced policy pro: easy onboarding
Markdown and GitHub knowledge is sufficient for a start.
"Documentation is as important as code" @FokusMan #FOSDEM #TooltheDocs #writethedocs pic.twitter.com/PXsZ148Opx
— Kristof Van Tomme (@kvantomme) February 4, 2018
Automatically Ensuring Quality of SUSE Documentation
Technical Writer at OpenSUSE Documentation Team
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)
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
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.
Publish docs to GitHub pages. ToDo: Integrate a style-checker without inundating people with error messages.
DAPScompare, their own DocBook validation sheet. Future plan: need more example docs.
PS: xxlt is only well documented in German.
It's tested or it's broken
Maintainer of the API testing tool DREDD at @apiaryio
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.
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"
"...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).
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.
"Design first. Docs first." @honzajavorek #FOSDEM #ToolTheDocs pic.twitter.com/ufsUjF7Ec4
— Shaun McCance (@shaunm) February 4, 2018
Introducing Open DevPortal, an open source CMS based documentation tool
Front-end Developer at Pronovix
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.
Keep pace with code changes
Collaborate with the contributors of the documentation
Anyone can contribute (Technical Writers, Developers)
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.
How a CMS could be used to integrate documentation from different repositories, while maintaining a consistent UI for readers and for casual contributors.
Extending Sphinx to automate your documentation
Software Engineer at Redhat
reStructuredText - syntax (write) Docutils - parsing (write, individual files) Sphinx - build, multiple cross-referenced files
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.
(not in Docutils)
Sphinx contrib, hundreds of extensions, you can use those the contrib ones mixed with your own.
topic-oriented help at the GNOME project
GNOME Developer, Writer, and Community Advocate. Runs the Open Help Conference & Sprints. Upstream documentation projects at RedHat Open Source and Standards department.
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.
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.
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.
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).
Topic oriented documentation with Mallard by @shaunm - live demo! #FOSDEM #TooltheDocs #writethedocs pic.twitter.com/DWThOqxnGl
— Kristof Van Tomme (@kvantomme) February 4, 2018
How to choose the right "path" for documentation in open source projects
Documentation Engineer at Netlify
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).
"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.
@LukasRosenstock @kvantomme @APItheDocs @pronovix Glad that you had that experience. They need to do something about their messaging.
@kittylyst @kvantomme I've been to the @APItheDocs conferences and never for a single moment I had the impression t… https://t.co/vzndwiYwBa
Want to discuss your #APIprogram with a group of peers? Facing #APIproduct challenges and new insights would be ben… https://t.co/4CuXwd3rj3
Great video recap of #dcpannonia with some cool folks 📹: https://t.co/pj0KUpesFD #Drupal #drupalcamp #Palic #Pronovix #sponsor
🆕New event in the #API scene 🆕 It's you, who defines the program – schedule emerges matching your real needs and i… https://t.co/gPCSIgVdud