DevRel Scribbles
  • What are Scribbles?
  • Index
  • Developer Advocacy
  • Developer Advocates
  • Life as a developer advocate
  • Modernising Red Hat’s enterprise developer program
  • Engaging 9-year-old software developers
  • Making 22-year-olds love 26-year-old software
  • Dogfooding developer products: gathering insights from internal hackathons
  • How far does your ethical responsibility stretch for the tech your devs create?
  • Outside the lecture theatre
  • How do you design programs for diversity?
  • Build the Platform Your Developers Actually Want
  • Measuring dev rel programs far beyond marketing activities
  • Developer Evangelism
    • Developer Evangelists
    • How to rock a technical keynote
    • The Art of Slide Design
    • The Art of Talk Design
    • The Art of Story Design
    • Dev events beyond 2021
  • Developer Experience
    • The Power of Content
    • Building a Developer Community in an Enterprise World
    • How to lose a dev in three ways
    • Developer relations, why is it needed?
    • The hierarchy of developer needs
    • GitHub is your documentation landing page
    • Docs as engineering
    • Commit messages vs. release notes
    • A11y pal(ly)- crafting universally good docs
    • Inspiring and empowering users to become great writers, and why that’s important
    • Solving internal technical documentation at Spotify
  • Community Management
    • Building community flywheels
    • DevRel = Community Management?
    • Creating high-quality communities
    • How to grow a healthy Open-Source community?
    • Managing communities at scale
    • Using community to drive growth
    • Useful community success metrics
    • Communities aren't funnels
    • How to mobilise your community during a pandemic
  • Managing a DevRel Team
    • Developer Relations + Product
    • Distributed developer relations
    • Understanding company goals
    • DevRel Qualified Leads (DQL)
    • Path to success for DevRel
    • How to move up in your organization
    • Four pillars of DevRel
    • Building your DevRel dream team
    • Managing the burnout burn-down
    • I messed up and I’m going to get fired
    • How to report on community relationships without being creepy about it
    • How to scale a developer relations team
  • Misc
    • Is developer relations right for you?
    • Tooling your way to a great DevRel Team
    • Planning your DevRel career
    • Success metrics as narratives
    • Get executive buy-in or else
    • Introduction to the AAARRRP devrel strategy framework
    • Strategy for developer outreach
    • Connecting dev rel and product
    • Performance DevRel
    • Ultimate cheat codes for healthier travel
Powered by GitBook
On this page
  • Summary:
  • Scribbles:
  • Problems
  • Docs as Code concept
  • Docs as Engineering
  • Testing and linting
  • Modularising
  • Pipeline

Was this helpful?

Export as PDF
  1. Developer Experience

Docs as engineering

Cristiano Betta shares the practicalities of how they have taken an engineering approach to their API documentation.

PreviousGitHub is your documentation landing pageNextCommit messages vs. release notes

Last updated 3 years ago

Was this helpful?

Summary:

Docs as Code

  • 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.

Scribbles:

  • 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.

Problems

What were the problems faced during the process of translation?

  • Hard to translate

  • No audit trail l

  • No review process

  • No modularity

  • Hard to refactor

  • Hard to ensure quality

Docs as Code concept

  • 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. ‌

Docs as Engineering

  • Necessarily not covering architecture -- but software engineering.

  • Software engineering, we’ve got a lot of principles that we’re all familiar with.

Software engineering principles

  • 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 and linting

  • 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.

Modularising

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.

Pipeline

  • 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.

‌

Box’s Docs Pipeline

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!!

Video