Docs as engineering
Cristiano Betta shares the practicalities of how they have taken an engineering approach to their API documentation.
Video
- Store your documentation in GitHub or SVN, or whatever you want to use, but these days a lot of it is in Git.
- Build the documentation automatically.
- Review the documentation as you write it.
- Publish the documentation without much user intervention.
- Test anything that can be tested.
- Making sure that your documentation quality is gonna remain good going forward.
- That kind of thing.
- Modularize to prevent duplication,
- So that we can reuse our documentation.
- Reuse -- All of that will allow us to maximize value.
- Using a pipeline to tie it all together.
- README allows you to make a backup, you export it.
- Turns out when you do import and export and import kind of thing, you’d expect it to be symmetrical. If I create export and I just import it over here again and should be getting the same system at the end. Not how it worked at ReadMe.
- Hard to translate
- No audit trail l
- No review process
- No modularity
- Hard to refactor
- Hard to ensure quality
- Store your documentation in GitHub or SVN, or whatever you want to use, but these days a lot of it is in Git.
- Build the documentation automatically.
- Review the documentation as you write it.
- Publish the documentation without much user intervention.
- Necessarily not covering architecture -- but software engineering.
- Software engineering, we’ve got a lot of principles that we’re all familiar with.
- Modularity: Writing modular code, and that we should
- KISS: Keep things simple, and that we
- DRY: Shouldn’t repeat ourselves, and that we should
- Anticipate change
- Do one thing well: The Unix principle of doing things well.
- To test early
- Testing early,
- Testing often,
- Testing the parts
- Testing the whole.
- Validate internal links
- Test at the source.
- For documentation, that means that if you test early, you want to There’s a couple of things you can do there.
- Test the unit.
- Spell-checking.
It’s the idea that you should break things into their components to make sure that they do one thing well, that they allow for easy inclusion.
- Do one thing well
- Allow for easy inclusion
- Composition over configurations
- And you allow composition over configuration.
- So rather than configuring things, you can take multiple components that you’ve written, combine them together into some nice, new bits of software
- Apply that same thing to our documentation.
- Ensure quality.
- So within the pipeline, we do our testing, we do our validation that our code still does what it’s supposed to do.
- It maximizes our value
- It allows us to ship to multiple locations quickly, faster, in parallel.
- It speeds up delivery
- Encourages responsibility.
- Because it basically says, hey anybody who documents, anybody who writes software, if you manage to merge this into master, it will ship, it will go live, it will be part of the product, it will go out there almost instantly.
Let’s look at the pipeline Cristiano’s team created to automate literally everything!
- Microcopy and guides
- This stuff is mostly markdown and a couple of YML files, as well as their open API specification, which is mostly YML.
- Travis
- Pick it up, do the spellchecks, do all the validation, etc. And then it writes it back to an English branch(English version).
- Every time the on branches get updated, or any time their SDK’s or Gatsby kind of source, which is the static site generator that they use.
- Netlify
- The serverless function basically determines which of our stages to trigger.
- Staging environment, master environment, and translation environment for their upcoming Japanese full translation.
- Netlify will pull all those sources in, build the site.
- Netlify -- also as a hosting provider.
- They took it a step further and they were not just building documentation at that point because.
We have great source materials now that we are validating and we’re sanitizing.
- Different build servers -- at the bottom, we have our in-house build server. So every time our English sources change, it creates a snapshot, translates it in house, sends it off to our translation teams, and then writes back to the Japanese file to a Japanese branch.
- Netlify will pick up any of these sources and build them out as documentation. But every time these sources change, Travis will also put it up and currently it’s pushing a postman collection.
- And it’s not just pushing it out in English, it’s also pushing it out in Japanese!!