DEV Community

loading...

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

Sylwia Vargas
I teach React, Redux, JavaScript, Ruby, Rails at Flatiron School | I care about web accessible and inclusive tech | she/her
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!