Talk Notes: "DocOps: engineering great documentation" by Adam Butler

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 by Adam Butler

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

Comments

[Kevin Gilpin]

Thanks for the write up! On a related note, I’ll be speaking at RailsConf next week on “Teaching your code to document its own architecture” - here’s that link - railsconf.com/program/sessions#ses...

After the talk, I will also present the content here on dev.to as blogs and videos. I hope you’ll check it out :-)

[Sylwia Vargas]

Ohhhh thank you so much for the info and the link. I have just gotten my RailsConf tickets and I'll make sure to attend your talk!

[Ella (she/her/elle)]

Thanks for this! Super helpful and relevant to where my head is at right now.

[Bojan Božić]

Thanks Sylwia, that's really useful!