DEV Community

loading...

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

sylwiavargas profile image Sylwia Vargas Updated on ・2 min read

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:

Discussion (4)

Collapse
kgilpin profile image
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 :-)

Collapse
sylwiavargas profile image
Sylwia Vargas Author

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!

Collapse
ellativity profile image
Ella Ang (she/her/elle)

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

Collapse
bozicb profile image
Bojan Božić

Thanks Sylwia, that's really useful!

Forem Open with the Forem app