Making Documentation Matter

Great open source documentation doesn’t happen by accident—it takes a whole team effort

I was two days into a new job when I came across something many developers can relate to: a cryptic error message upon installation. I did what many people do and Googled the error message. I was delighted to find a StackOverflow question with the same error… until I realized that there were no solutions in response, and the question had been asked by one of my new coworkers! I walked up to him and asked him about it in person. But it made me wonder—wouldn’t it be better if these answers were written out in documentation somewhere?

Every question is an opportunity to learn, teach, and write documentation.

Whether it’s for installation bugs or constantly updated open source libraries, asking developers to take the time to document how to use them properly can often be met with resistance. It’s understandable; building documentation time into a busy sprint can be difficult. But it’s not impossible, and as we’ve discovered here at Reaction Commerce, it’s essential.

At Reaction, we’ve taken concrete steps to embed a culture of documentation across the engineering teams. And we do not have a single full-time, dedicated technical writer on staff, so everyone takes part in the process. How did we get to this point? It’s been an ever-evolving effort from our entire team.

Embedding documentation culture starts with a safe environment for questions

Since I started at Reaction, I’ve heard the following rule repeated so many times it’s become a mantra:

“If someone has to ask how to do something more than once, make sure to document it.”

Sometimes it’s a question in a team Slack channel about how to perform a certain step in the release process. Or it’s an often-asked question in the public Gitter channel about a Reaction feature. Either way, our engineering team leaders’ commitment to this rule has two positive effects: First, it supports everyone in feeling safe to ask questions in group environments. Second, it ensures the question actually gets answered, and then documented in a more permanent place.

Every question is an opportunity to learn, teach, and write documentation. And it’s the responsibility of team leadership to foster a safe environment to openly ask questions and encourage documentation. For our senior engineers at Reaction, our mantra was born from their previous experience on development teams and in building open source tools for the JavaScript communities.

“I had a lot of experiences … working either for companies that document really well or companies that don't, and then also reading some of my own open source packages and tools, which kind of taught me that you can make the coolest package in the world and if you can't explain to people why it's cool and how to use it, nobody's going to get it,” says Eric Dobbertin, Reaction senior engineer and author of some of the most used Meteor packages, like collection2, autoform and simpl-schema.

As the team has grown from a handful of people in the Santa Monica office, to engineers and managers spanning both hemispheres and three continents, having a process to make sure everyone’s questions get answered, openly and asynchronously, has been vital to team productivity.

Everything we do is useless if people don’t know it’s there, or don’t know how to use it properly.
Eric Dobbertin, Reaction Senior Engineer

Better documentation needs developer-centric tools

Even with this kind of documentation culture in place, a team needs frictionless tools to help people find the answers when they need them, and make writing and deploying easier. Over the past few months, we’ve made a few design changes in our reaction-docs repo and Reaction Documentation site to better handle the volume of documentation we create.

Meteor => Docusaurus
We switched from a homegrown Meteor doc app, redoc, to Docusaurus. Although the main stack—templates based on JavaScript and React, with documentation written in Markdown—has remained the same, Docusaurus has given us a big feature often requested by our community: better search. Specifically, with robust search from Algolia’s DocSearch.

Switching to Docusaurus has also helped us upgrade some of our older technologies, like the Prism syntax highlighter that better supports JSX and GraphQL.

Documentation within code
Aside from the main docs site, two of our newest projects, the GraphQL API and the Reaction Design System component library, have allowed us to write documentation within the code and present it in a more interactive way.

Like any GraphQL API, ours is self-documenting. Opening localhost:3000/graphiql will open a playground to read and inspect the API.

Reaction GraphQL API

Another example of merging documentation and code with developer tools is our Reaction Design System. Combining our @reactioncommerce/components package of React components with React Styleguidist, we’ve deployed a separate site dedicated solely to front-end design guidelines and React components.

So, as a developer creating a new component, I’m now able to run a super-fast site to not only test my component, but also document it. Whether it is a basic component with many variants like a Button, or a complex higher order component like a Checkout Action, React Styleguidist gives developers and designers a place to render the component, test various props with different data, and document it.

Reaction Design System

The site serves as a constantly changing and living documentation, with our pull request branch preview sites. We’ve configured Netlify’s branch deploy feature so each new commit pushed to a pull request to the repository triggers a deploy to a preview site. Designers and developers alike can test the component in different browsers and devices on a test URL, like this AddressForm component’s preview site from this pull request.

Getting into the writing habit: 4 ways to improve your team’s writing

Not every team is quite ready to commit to a strong documentation culture like Reaction’s. Even so, there are a lot of smaller steps you can take to embed opportunities for better writing and communication in your engineering process.

  1. Require detailed pull request (PR) templates: Reaction’s default pull request template, might be longer than you’re used to. That’s because it’s not just a way to keep a log of changes coming into the app, but also as a way to begin documenting code and feature changes, with clear instructions on how to test them, screenshots of the visual changes, and notes of any breaking changes.

  2. Add a /docs/ folder in every project: All projects initialized with our project generator come out of the box with a /docs/ folder for project documentation and architectural decision records (ADRs). The storefront repository has a good example of these docs and ADRs. Note: An extra benefit of keeping documentation within the same repository of the code itself is being able to review both new code and new documentation in a single pull request.

  3. Enforce JSDoc with ESLint: The Reaction ESLint configuration, combined with continuous integration at every pull request, requires all new JavaScript methods to be documented with JSDoc.

  4. Write and edit release notes and CHANGELOGs collaboratively: You might have noticed that our release notes are more detailed than many you’ve seen. Our release notes used to be a mere compilation of commit messages from each pull request. No longer. Along with the release pull requests, the engineering lead and others collaborate to add more useful information to the release notes. It’s a relatively easy way to add a lot of valuable information in a short time.

Building a strong documentation culture doesn’t happen overnight, but it’s something that can be embedded into your engineering team’s daily process. As Reaction’s teams and products evolve, our documentation practices and output continue to change as well. It’s all a work in progress, so let us know what new features we should add to our docs, or what we could be documenting better.

comments powered by Disqus