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
withconst
andlet
), you don't need to manually replace that but instead, it's automated - screenshots
- link testing
- spelling and grammar
-
code examples: all of the code examples are in different repos; if you implement a major guidelines change (e.g. replace
-
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
Top comments (4)
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 :-)
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!
Thanks for this! Super helpful and relevant to where my head is at right now.
Thanks Sylwia, that's really useful!