Better Docs
How We’re Building a Culture of Documentation
Every year at BuzzFeed, we run a Global Employee Survey that tells us the areas where we did great and not so great in the past year. In the 2017 survey, there was one area in particular where our tech department felt we did very poorly: technical documentation. This survey triggered the creation of the Better Docs initiative: a group of people who were willing to do something about this problem.
One year later, we managed to change the perception of technical documentation drastically from only 29% of the team being happy with the state of our documentation to 70%!
Even though there is still loads to be done, this is a huge success, and we want to share what we’ve learned in the past year on how to build documentation into our culture.
4 Documentation Questions You Need to Answer
As a first exercise, we believe it’s important to answer four very basic questions. Your answers will depend on your tech stack and company’s size, goals, and culture. It’s good to be as candid as possible when answering these questions, and try not to fall into the trap of wishful thinking about what is possible or not for your team.
- What should be documented?
- How should it be documented?
- Who should document it?
- How can you make your documentation discoverable?
Let’s take a look at each one in more detail.
What Should Be Documented?
You might be tempted to say, “Let’s document all the things!” But the reality is it’s not only hard but often suboptimal. Here are the things we decided to document.
Code and Project Documentation
To make sure we cover crucial elements for our services, we created a standard that our service’s README files should meet. Here’s what the standard template looks like:
README.md# _name of the service_
## Point of contact and Slack channel
## Usage
## Running the service
## System
## Runbook
## Monitoring
## Documentation
# _name of the service_
Each service needs to have a section explaining what the service is doing and why.
## Point of contact and Slack channel
Then we need to mention who a point of contact is: a team responsible for this project, concrete names of people who would help you with questions, and a Slack channel.
## Usage
Usage explains how the service is used. If it’s an API, what do we call it? We try to give real-life examples a curious developer could try when interacting with the service for the first time.
## Running the service
Next, there is Running a service, which tells you how to start the service and the ways to access it.
## System
Lists all the dependencies and technologies the service uses. Does it sit behind a CDN? Is it Python/Go, etc.? We try to highlight particularly critical or nonobvious dependencies. It’s important to understand — especially if your infrastructure consists of microservices — how things relate to one another.
## Runbook
Links to the document that is a compilation of routine procedures and operations the system administrator or anyone in the tech team could carry out when something goes wrong. The person who knows the most about the service isn’t always available when there is an outage, and having a runbook in place helps anyone be empowered to help.
## Monitoring
This section covers links to any existing monitoring: logging, dashboards or alarms that help us notice outages as soon as possible.
## Documentation
Finally, in this section link to any additional documentation: architecture diagrams, architecture docs, proposals, any business logic documents, and so on.
So, in fact, what we require for each service’s documentation is quite limited: only eight points. These eight points cover the most crucial things we need to know about a service from the code and project level. They help us maintain certain standards for our services. Just by looking at what we are required to document in the README file, we will be reminded of questions such as these:
- Are we actually logging the right things?
- Have we added necessary instrumentation to our service, and do we monitor any problems and performance issues in the given service?
- Are we prepared for our service to break? What would be the impact on other parts of our infrastructure?
Since BuzzFeed Tech is distributed across multiple time zones, our goal for this document is to make sure anyone, no matter which team they’re on, can understand why the service exists, how it fits into our existing architecture, and how to set it up locally without asking anyone for help.
We have shared our README guidelines here if you are interested in more details.
Architecture Documentation and Proposals
Apart from code and project documentation, we also keep system architecture documentation and proposals. Having them documented allows for better collaboration and gives people an equal chance to participate in technical decisions no matter where they are based.
Best Practices, Processes, and Onboarding
One of our Tech Leadership principles at BuzzFeed states that leaders in BuzzFeed “practice generosity,” which means that helping other people grow and broaden their knowledge and skills is something crucial to being successful at BuzzFeed. Documentation is one of the tools we use to share our experiences and be generous with one another. Without it, the impact we have on our company culture would be strictly tied to location and size of our office.
That’s why we document things like best practices, processes, workflows, runbooks, postmortems, how we test, how we deploy, deployment checklists, onboarding documents, and so on and so forth. Anything that helps us be a stronger team is a good thing to be documented.
How Should It Be Documented?
Once we know what kind of things we want to document, it is time to decide how it should be done.
Markdown
For code and project documentation, we wanted to keep documentation as close to the code as possible. We decided to use markdown files inside our Github mono repository. Each service requires one top-level README file that should meet the criteria mentioned previously. Any additional code-specific documentation should live in the top-level /docs directory in the service.
This ensures that once you fetch your repo, you have documentation about your service in place.
Google Drive
For system architecture documentation, proposals, best practices, and workflow documents, we decided to use a shared Team Drive on Google Drive because
- Google docs allow you to collaborate, comment, suggest, and share documents easily (and you can collaborate with anyone, not only tech folks!);
- Team Drive allows shared ownership of the file — no more issues with permission to the doc, and the doc is not gone if the owner leaves the company;
- and it improves transparency and allows people to see how other teams are working.
Who Should Document It?
Everyone
Something you might find curious when looking at our documentation is that everyone in the tech organization has the ability to edit the content. The decision to give everyone edit access was a turning point in building our documentation culture. Trusting that people won’t abuse this power sends a very powerful message: We are all responsible for the state of our documentation.
Documentation Team
To make this work even more efficiently, we formed a Documentation Team (Better Docs), which
- sets standards and helps keep documentation consistent;
- advises upon and suggests solutions for documentation;
- gathers feedback, finds patterns, and identifies pain points in our documentation;
- educates and promotes a culture of documentation within the company;
- and works in a transparent way, making it easy to join and contribute at any point.
How Can You Make Your Documentation Discoverable?
We created a “Tech Docs and Where to Find Them” Google doc. It compiles the most crucial information about documentation: what we document and how — all the things mentioned when discussing the questions “What should we document?” and “How should it be documented?”
We also tried a couple of programmatic solutions (i.e., writing a documentation Slack integration), but that turned out not to work as well as we had hoped. It turned out that fixing a human problem with technical solution is not necessarily the best approach.
What worked better for us in the end was simply reminding people about the documentation standards through email and Slack and by answering questions from the team members and organizing documentation events.
But Where to Start?
Starting a documentation culture in your company might seem like an overwhelming task. If documentation has no clear owner in your company and there are many services missing proper documentation, the amount of work might seem terrifying!
Here are some tips we have for you.
Form a Documentation Working Group
Gather people who are passionate about the topic and form a working group. Your experiences and needs when it comes to documentation might be completely different as someone else’s, so make sure you invite a diverse crowd to participate. See what you have in common, and share ideas on what could have the biggest impact in your company.
Lead by Example
Set a great example by encouraging the addition of documentation in your own team. You could start small and use your team to show that you could improve your work by having good documentation in place.
Be Transparent
Make it obvious where people can go to chat and share ideas about documentation. Where should interested people find advice? Otherwise, everyone will be trying different things to solve their own problems without a chance to share their approaches with a broader audience.
And finally — and this is one I love so much:
Create the Brand
There is nothing more exciting than to build a brand and a community around it. And it’s easier than it seems: logo, stickers, and a memorable name can help a lot with that. It somehow makes it feel more serious and professional. And, in a way, pretty fun…
Organize an Event
Make some time for everyone to be able to focus on documentation. In January, we ran a one-day event (Doc Day) where our whole tech team was encouraged to work exclusively on documentation.
We formed teams, set goals, and tried to make it as fun as possible. We had a tasty breakfast, lots of stickers, and the feeling of a common goal. It was super successful and made people excited about writing documentation, encouraging them to start writing documentation in their projects.
Don’t be afraid to bribe people with a pile of cakes or a tasty breakfast if it will motivate everyone to fix the documentation problem in your company. ;)
Is Your Company Ready to Support Documentation Culture?
Ultimately what worked for us in BuzzFeed was not writing all the docs ourselves as a small team but creating a culture of documentation where everyone is encouraged to make a difference.
In order to make this possible in your workplace, there are some things to keep in mind:
Is your company actually ready to support a culture of documentation? I’m sure that if loads of companies were asked if they care about documentation, they would answer, “Yes!” without hesitation.
But do they really?
- If you decide to work on documentation during your work hours, are you sure your work will be noticed and appropriately rewarded?
- Is it taken into account during performance review and promotions?
- Is it valued as much as writing actual code? If not, how can you expect anyone to invest time in writing documentation if it is not progressing their career and is not recognized?
- Does tech leadership support documentation initiatives, and how? (Examples of the support we got for Better Docs in BuzzFeed included public praise, clear communication that tech leadership values the work we were doing, taking our documentation work into account during promotions, and allowing 200+ people in our tech team to stop working on their current projects for a whole day to work on documentation during Doc Day.)
Is your company willing to spend money, time, and resources to improve documentation? Are you sure documentation is not one of the invisible tasks people from underrepresented groups end up doing without ever getting recognition for it?
If you are able to say that your workplace is able to support you in building a culture of documentation, first: Congratulations, you are very lucky!
And my next bit of advice for you?
Make It Fun!
One of the big things that helped people notice Better Docs was creating a brand: events, stickers, funny but informative emails (full of GIFs), or things that make documentation process a fun experience (like these diagram monsters — thanks, Rowan and Eddie!). I can’t even tell you how excited people were when the monsters were introduced.
It’s all about making the process an enjoyable experience.
You Can Do It!
Is it possible to create a culture of documentation in your tech team? Absolutely! It’s not easy — it’s a hard fight to win — but it can be fun and rewarding. And to quote my colleague Alice DuBois (from the email she sent to encourage her team to actively participate in Doc Day):
Think back to some time that you asked a colleague for documentation on a service you needed to use and that colleague immediately sent you to a doc that was clear and up to date.
HOW MUCH DID YOU LOVE THAT PERSON? Well, you could be loved that much.
To keep in touch with us here and find out what’s going on at BuzzFeed Tech, be sure to follow us on Twitter @BuzzFeedExp where a member of our Tech team takes over the handle for a week!
