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.
“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,
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.
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.
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.
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.
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.
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.