How HashiCorp Makes Writing a Priority

The start of the COVID-19 pandemic and resulting shift to remote work was a big wake-up call for many companies. With workforces distributed, companies need a better way to share knowledge, and they need it fast. Teams now have a priority to develop a system for documenting their knowledge.

We spoke with Kevin Fisher, Chief of Staff at HashiCorp, to learn how teams can build a culture of documentation that scales as they do.

Good Writing Means Good Work

A strong culture of writing and documentation is increasingly essential for teams to make good decisions and do their best work. Writing helps the HashiCorp team:

• Gain clarity. Writing encourages thoroughness and detail in decision making. Information delivered in writing is less likely to be misinterpreted than if shared verbally; you can be more precise with your language.
• Provide feedback. In written form, knowledge can easily be reviewed and critiqued. HashiCorp employees are very good at critiquing the written ideas without personally criticizing the author. The full team is dedicated to making the decision as best as it can be without personal attachment to ideas.
• Save time. Rather than using endless meetings to debate decisions, proposals can be reviewed in full detail before a meeting. Then the meeting is dedicated to specific questions and making a final decision.
• Collaborate across time zones. For companies with a majority of their employees working remotely, especially if they are widely dispersed geographically, it becomes almost unavoidable to write. Fishner sees writing as a way “for people to still be in the loop and contribute and be heard, regardless of what time zone they work in."

Building a Culture of Documentation

If your team has historically struggled with documentation, it may feel like it's too late to turn things around. But don't worry — it's never too late to start investing in a culture of writing. The longer you wait, the more committed you will need to be, Fishner says, but it's always possible to make documentation a priority.

He recommends three main levers to promote writing across a team: leading by example, making documentation an expectation, and defining a process.

Lead by Example

Writing is encouraged and often required within HashiCorp, and it starts at the top. Company executives are comfortable with documentation and execute their primary responsibilities through writing — they serve as role models, demonstrating the very skills they require of their employees. At the same time, their work product serves as an example of the desired quality in documentation.

Fishner makes it clear that leading by example is essential for making documentation a priority. Whether you're an executive or a team member, if you want to instill a writing culture — just start. For the next decision you need to make, propose it in writing. Other colleagues involved in that process will appreciate the effort to write a detailed proposal, and potentially adopt it for the next time they need to make a decision. Good practices that produce good outcomes are easier to spread. He recommends identifying company leaders who can serve as role models for good writing, and have them create examples through their own work. As long as leaders keep writing, Fishner says, a culture of documentation will endure.

“As long as leaders keep writing, a culture of documentation will endure.”

Larger companies should start with one team and make writing a priority within that team. This allows you to experiment and figure out what works and what doesn't before taking your learnings company-wide. Starting with a team that already exhibits good documentation practices will help give you a leg up.

No matter your company size, the longer you wait, the harder it will be to adopt writing-based practices. Lead by example, and others will follow.

Make Documentation an Expectation

Making documentation an expectation for making decisions will help you shift your company culture towards writing. At HashiCorp, important decisions are not accepted unless they're written down, and many teams specifically include writing as an area of evaluation during performance reviews.

Prospective employees are also clued into the importance of writing at HashiCorp. Product manager applicants, for example, are required to complete a written case study, in which they produce a 24-month product strategy and a 12-month roadmap, all in two pages or less. This makes it very clear to prospective employees that writing will be key part of the role.

It's important to note that there isn't just one way to write effectively. Don't over-index on a certain type or style of writing, or a perceived level of quality, as these can be limiting barriers. As Fishner says, “Just because there is a set template that we follow doesn't mean we expect everybody to write the same. People approach problems differently. People communicate differently. So, there's a responsibility on the reader to also put in an effort to understand. It's not just all about the writer.”

“There's a responsibility on the reader to also put in an effort to understand. It's not just all about the writer.”

Create a Clear Process

In Fishner's experience, business writing is a skill that can be continuously improved. Creating (and documenting!) a clear process for internal writing and documentation is an easy way to help your employees learn.

First, decide what should and shouldn't be written down. At HashiCorp, the guideline is relatively simple: if it's a major change within a team or if it's a minor change affecting multiple teams, write it down. Everything else can be discussed verbally or via email or Slack.

For just as under-documenting can waste time and cause confusion, so can over-documentation. If you're unsure where to start, Fishner recommends defining what constitutes a major versus minor change.

Then, outline the process. For HashiCorp, research is the first step, then writing, then feedback. To help streamline the writing step, consider making use of templates. This gives employees a better understanding of the underlying structure that supports effective writing. The the two primary document types used across HashiCorp are the PRD (Problem Requirements Document) and RFC (Request for Comment).

Aim for Improvement, Not Perfection

There's no one-size-fits all solution for becoming a company that practices effective writing and documentation. Be patient, and be prepared to try out multiple strategies to see what works for your company.

Great documentation is not going to spring up overnight, so don't aim for perfection right away, and simply focus on what works. Start with small goals, and celebrate your wins. After all, just by reading this, you've already undertaken the hardest part — getting started.

To learn more about HashiCorp's writing practices and view their PRD and RFC templates, check out the How HashiCorp Works article.