May contributing.today: on technical documentation, docs tools and markup languages

I try to make a habit of writing summaries for our contributing.today meetups. For background, read this post.

May 11th we talked about all things docs.

Our esteemed panelists:

• Tony Ibbs aka Tibs (@much_of_a on Twitter), Developer Educator at Aiven and recovering (Python) developer. Tibs was the kind of developer that would leave a trail of documentation behind. He was there when Python docs adopted reStructuredText and immediately fell in love with the project.
• Alexandra White (@heyawhite), Technical Writer at Google, covering the Privacy Sandbox.
• Scott Riley (@scott_riley), Head of Product & Design at GitBook which - and I quote - helps you publish beautiful docs and centralize your team's knowledge.

Docs favsies

Alexandra mentioned WordPress as an example of an open source project with great documentation, but granted they have a team dedicated to docs.

Tibs is hard on documentation, but some of his favorites include PostgreSQL (it's extensive!), the Redis commands docs (beautifully laid-out), and - a silly one - Pollen, which explores what would happen if Lisp would be written in LateX, and the documentation is an homage to typography.

Scott enjoys the Svelte docs, with its many tutorials. "They give the reader credit, without making a lot of assumptions. And they have a sandbox for you to play around and get familiar with Svelte." Not strictly docs, but an excellently designed learning experience is Exercism, says Scott.

Best practices and frameworks

Docs as Code meets engineers where they are, says Alexandra, but DoC has become synonymous with static site generators, and she's not sure if static site generators are always the right answer. First things first: make the docs.

Tibs is a big fan of the Ditaxis framework, and "instead of writing random things and hoping those are useful, to think about the different types of use." They are also a firm believer of - when possible - having text be (plain) text: something everyone can work with.

Scott agrees that using a broad format like markdown allows for more people to be involved in for instance reviewing the docs. He advocates for user testing your documentation. Observing people while they read and try to make sense of your documentation is immensely useful. Risking breaking some hearts, Scott says that "nobody comes to our docs for fun, learn how you can help them achieve their goals."

In terms of what is a good minimum viable documentation for a new service/product, Tibs says: "When it's a command line tool, always have a help command, before you implement anything else."

"Documentation writing often comes later in the process of development than I as a technical writer would like", says Alexandra. Writing documentation before writing code gets the thumbs up from all panelists.

Setup or install needs to be documented. Alexandra: "After that people can tinker around, but they need to know how to even get started".

Scott: "You probably don't need FAQs for a new project, they're not frequently asked yet. Don't look at Stripe for comparison, look at the open source project next door."

According to Tibs you need at minimum a README with instructions on how to get started (and someone making sure that information is up to date), setup instructions for the docs in your contributing file, and a license that applies to your docs specifically.

Accessible and inclusive docs

"It's important to make sure that people with disabilities can access your documentation, but/and anything that you do to make your docs more accessible will make your documentation better for everyone", says Alexandra. She shares three things to keep in mind:

• Be clear and concise, avoid jargon (or: make sure the definition can be found in a glossary)
• Well-organized semantic HTML (make sure to use real headers, not things that are styled to look like headers)
• Under no circumstances use PDFs

Tibs: "Start with plain text, generate all the things - even PDF - from it."

The need for accessibility can be situational and temporary. When we're designing fundamentally good docs, you'll automatically pass accessibility tests with flying colors (pun sort of intended). Accessibility is never "done", and Scott suggests you research how a neurotypical person, or a person with ADHD perceives your documentation.

For their (or: our, I work at Aiven after all) developer documentation, Aiven uses Vale to enforce the editorial style guide. Vale is a linter that is highly extensible with rules and packages that check for inclusive language, and using alt text, among other things. Scott adds: "Linters are a great tool for introspection, you'll learn from what they flag."

Alexandra recommends dogfooding your documentation using the tools W3C lists.

We got side-tracked just a bit talking about people having different ways of successfully absorbing information. Some prefer text, some prefer video, there is no one-size-fits all solution.

Emojis, while they maybe shouldn't have a place in your docs in the first place, are inaccessible.

Contributing to docs

Scott: "If you're doing Docs as Code and you're looking for contributions, make sure that you specify in your CONTRIBUTING.md file how people should contribute to your docs."

Tibs encourages people who want to start contributing to open source docs to find a project that is willing to put in the effort of onboarding them.

Alexandra shared Google's Season of Docs program, which connects people who want to do technical writing with open source projects looking for writers. "It has funding behind it, and puts documentation front and center."

Scott: "Please don't self-select out of contributing because you think you're not technical enough." It's even better if you're not an expert, because how many users of any given project will be on that expert level? "If something is very text-heavy and you're a regular user, add screenshots or record gifs of you clicking through some of the steps described."

All panelists praise Write the Docs for the wonderful community it is. If you're (starting to get) excited about docs, join their platform and events and find people just like you!

A round of "unpopular opinions":

• Scott: don't gamify your docs.
• Tibs: reStructuredText is the best among markup languages.
• Alexandra: documentation isn't free.

For past sessions, check out our playlist on YouTube. This June well talk about funding and sponsoring in/for open source: https://contributing.today

PS: Liked Tibs' Keming shirt? Read the original keming post and order your own.