Talk Notes: "DocOps: engineering great documentation" by Adam Butler
Tags: techtalks
Published: 2021-03-29 15:19:53

**What is this post about**: As a part of my professional growth, I make time to watch conference talks on Ruby, Rails, JS, React, and tech writing. Previously, I'd just watch them but now I will take and publish notes for future reference.

**Talk:** [DocOps: engineering great documentation](https://www.youtube.com/watch?v=AnvqMb1VT40) by [Adam Butler](https://twitter.com/labfoo)

**One-sentence summary**: Help users and other developers contribute to your docs by following Open Source guidelines, choosing intuitive tooling, and automating your processes. 

**Impression**: An interesting intro to DocOps + an insight into how documentation is managed in a big company.

---

## Intro
- **DocOps: managing and maintaining documentation tooling**
- Engineering aspect of the documentation
- Typically, the process looks like this: 
  - tech writer talks to the product owner who talks to the engineers
  - this works with few products but the more products, the more tech writer will be overwhelmed
- There are a few stakeholders:
  - **engineers:** they have the most complete understanding of how the API behaves
  - **product owners:** understand the customer needs
  - **tech writers:** focused on readability and approachability 
  - **customers:** they are the first ones to notice issues so it makes sense to give them a way to contribute
  - **customer support:** resolving common issues
- Q: How can we engineer the process of writing the docs? 

## Engineering the docs
- Good Open Source guidelines:
  - good readme
  - code of conduct
  - contributing guide
  - licenses
  - templates for PRs
- Tooling
  - Ruby on Rails + Markdown
  - Rails, as a framework, gave them the opportunity to shape the docs as they wanted (vs Jekyll that would have stricter rules)
  - Slack + bots
  - `Markdown` is easy, popular, readable by humans and machines, can be quite powerful
  - They extend Markdown with Middleware

    > When trying to encourage collaboration, going for what's popular and easy makes a lot of sense

- Middleware
  - it's a pipeline: your file gets modified by a filter, then again until it gets translated into the html
  - 22 filters are involved (15 while the file is a markdown file, 16th is when the conversion happens), for instance:
  - **frontmatter**: regexing the frontmatter out and passing the rest
  - **tooltips**: implicit (headers, external links), extended (labels, collapsible content), plugins (scripted screenshots)
- Contribution Guides
  - Maintaining the docs is hard
  - Style guides
  - Code example guides
  - Stuff like the tone of voice, placeholder values
- Automation
  - **code examples**: all of the code examples are in different repos; if you implement a major guidelines change (e.g. replace `var` with `const` and `let`), you don't need to manually replace that but instead, it's automated
  - screenshots
  - link testing
  - spelling and grammar
- **Docs-like code**
  - a movement to take all the engineering processes and apply them to the documentation, for instance, re-using definitions

## Read more:
- Write the Docs, API the Docs
- "Docs like code" by Anne Gentle
- [Adam's post on Middleware](https://lab.io/articles/2017/02/12/extending-markdown-with-middleware/)