Our writing roots date back to the company’s earliest days, when the entire team was just the co-founders, Mitchell Hashimoto and Armon Dadgar, working out of Armon’s living room. Back then, it was pretty easy to keep the company aligned. But Mitchell and Armon still wrote down everything to help them think things through. And we do the same today—we write to clarify our ideas, to articulate concepts to our colleagues both within and beyond our teams, and to gather the feedback we need to make those ideas better.
When it was just Armon and me, we wrote everything down because it helped us clarify what we were doing, and kept us from falling down rabbit holes of solving problems that didn’t exist.
The process of writing encourages thoughtfulness. And it’s incredibly valuable for everyone to have easy access to context on what a decision is and how it was made, including the options we decided against.
HashiCorp’s writing culture is our superpower. We get to see how our colleagues think, emulate those processes, and get smarter ourselves.
Writing is one of the reasons why HashiCorp can successfully operate across time zones. It's tempting for teams that work in one region to make decisions synchronously and skip the step where options are written down. Reminding ourselves that all communication should be inclusive of everybody no matter where they are based is an important factor of building a resilient team in a remote company.
Of course, HashiCorp’s writing culture has evolved along with the company—not only in terms of how we write, but also in who does the writing. For the first several years, writing was much more common within Engineering than in other organizations. Now as we have more cross-functional initiatives, we’ve seen the adoption of writing-based processes increase dramatically.
Writing serves as an equalizing force to make sure great ideas are shared—and properly credited—no matter where they come from. The process for proposing a change in writing is the same whether you’re a junior employee or a company founder, and you’ll get to present it directly to your colleagues rather than relying on word-of-mouth. The same is true if you’re someone less likely to speak up in a meeting—or, because of time differences, to attend one. And as the company grows, we’ve found writing to be especially helpful in onboarding new hires; documenting our decision-making processes can be invaluable in helping a new team member get up to speed on the HashiCorp history relevant to their role.
A meeting is great for brainstorming. But in two years, when you’ve doubled in size and a third of the team are in new roles, who’s going to remember the details of how you reached a decision?
As for how we write, things have come a long way from the days of Mitchell and Armon starting with a blank page—though like the rest of our writing, anyone in the company can still check out those original documents on HashiCorp’s Google Drive. Now we have standardized templates for documents used across the company and within particular departments (design briefs in design, success plans in sales). Success plans for example are used to ensure everyone on the HashiCorp account team knows why the customer bought our products and how we can make them successful. Using standard templates helps us be thorough and support the customer from pre-sales through post-sales.
We’ve embedded HashiCorp institutional knowledge in our templates and removed the anxiety, both internally and for the customer, of feeling like success with our products is solely dependent upon the few individuals on the account team vs. the whole of HashiCorp and our extended community.
Even though some groups have function-specific writing practices, the two document types used across the company are the PRD (Problem Requirements Document) and RFC (Request for Comment). These documents have become an integral part of our shared language and core decision-making processes. Most large projects start with a PRD to define the problem and are followed by an RFC to propose a solution.
The Problem Requirements Document (PRD): Define the “Why”
HashiCorp’s PRD template is designed to help our team members fully understand a problem and define what’s needed to address it. A PRD is most helpful for working through an ambiguous challenge with many stakeholders. Generally, a PRD is the first step toward an RFC, but not always. Like any document at HashiCorp, you should decide whether to write a PRD based in part on whether recording your thought process will help fellow team members, current or future.
If you take the time to work through your thoughts, you’re probably going to avoid spending lots of effort pursuing ideas that turn out to be non-starters, and that saves everyone time.
Writing a PRD is about curating information, not creating it; you should go into the process without preconceived notions of what you’ll find. In most cases, you’ll start by creating a research plan, which can include interviewing users, talking with internal stakeholders, reading market research, and, if appropriate, experimenting with related software. When you’ve finished drafting your PRD, you’ll share it with your colleagues for feedback—and ideally offer them both a clear problem statement and novel insight on the problem space itself. A PRD reader should clearly understand what the problem is, who it affects, and why it is important to solve.
The Request for Comment (RFC): Proposing Solutions
Once you’ve defined a problem with a PRD or otherwise, the next step is using the RFC template to propose a solution. Oftentimes the person writing the PRD and the person writing the RFC are different. For example, product managers usually write PRDs and engineers follow with an RFC to address the problems surfaced in the PRD. The RFC process helps you to articulate—and get feedback on—the solution you’d like to propose. Your teammates have valuable experience in areas you may not, and they can help you surface “unknown unknowns” early on.
Sometimes, I’ll get really deep into something and think I have it figured out—until I start building and realize I’ve talked myself into a different reality. The RFC process helps confirm that the solution I’m planning actually solves the problem.
Whether you need to write an RFC or not is a qualitative decision; there are no specific requirements in place. It’s a good idea whenever you need more clarity around your solution—or when you want to create awareness across stakeholders. In general, RFCs should be written for impactful changes like major new features, revamping a portion of the website, or creating a new cross-organizational process. If a change will affect many stakeholders, an RFC should be used to drive clarity and consensus. If implementing your idea will take less time than writing it up, you can probably go ahead without an RFC. But you should consider whether to write one after the fact, to create a history of your work.
I write an RFC when I’m looking for a lot of consensus and buy-in—or a lot of commentary. If a decision is stimulating conversation, that’s a good indication that we should start writing things down.
It can be a struggle to sit down and write. I just want to go make my idea reality. But starting is the hardest part. I push myself to fill in the background and the proposal and to outline the headers for the rest; then I just have to fill in the blanks.
Once you’ve written the first draft of an RFC, share it with your team. They’re likely to have the most context on your proposal and its potential impacts, so most of your feedback will probably come at this stage. Any team member can comment on and approve an RFC, but you need explicit approval only from the appropriate team leads in order to move forward. Once the RFC is approved and shared with stakeholders, you can start implementing the solution. For major projects, also share the RFC to the company-wide email list. While most members of the mailing list will just read the email rather than the full RFC, sending it to the list gives visibility into major decisions being made across the company.
Best Practices and Pitfalls: Tips for Writing—and for Feedback
If you have an idea for a PRD or RFC and haven’t written one before, make use of an experienced “buddy” who can walk you through the structure, what to include, and what’s best to leave out. This person can review your draft before you share more broadly. Ask your manager to help you find the right buddy for your first PRD or RFC. Remember, all good writing takes practice, and none of your reviewers will be expecting perfection.
Collaborate early and often! I like to ask for input from someone who’s close to the subject matter—or who’s great at writing the type of document I’m creating.
Don’t get bogged down trying to make a document perfect before sharing it—just make it good enough to convey your point. It’s important to have co-workers help guide the process.
Regardless of what you’re writing, if there’s a template, do your best to follow it. A document with a familiar structure will be much easier for reviewers to navigate. Our RFC template, for example, is designed for readers to exit at any time. Your teammates may read the entire thing, but someone who isn’t a major stakeholder can simply review the background and proposal sections before moving on.
One common pitfall, especially for people new to the HashiCorp team, is to put too much detail in a document. In most cases, a background section takes only a paragraph or two, and a proposal takes one. The implementation section of an RFC might be a couple of pages. For the sake of yourself and your readers, be as efficient as you can.
Keep things short and be respectful of your readers’ time. While it might take you longer to write concisely, doing so makes your ideas clearer which results in better feedback from readers.
When feedback on something you’ve written starts coming in, acknowledge and resolve each comment, even the ones you decide not to act on. And if a response seems off the mark, ask questions to make sure you understand.
To make giving feedback easier on my teammates, I’ve started what we call ‘goalie mode.’ I’ll tell them I’m going to be hanging out in the doc for the next hour, and I respond as they make comments so we can resolve issues quickly.
If you’re the one giving feedback, there are a few best practices to follow as well. First, just as you would in any interaction, be kind. Make your comments constructive, and assume good intent—and good knowledge. An RFC, for example, was likely written by someone who, thanks to the process of creating the document, has more expertise than you. If you think they’ve left something out, don’t ask, “Why didn’t you think of this?” but rather, “I noticed you didn’t mention this. Can you clarify for me?”
I try to structure my feedback in the form of questions, such as asking about the impact of a particular decision. Encouraging an open dialogue helps us open up assumptions.
To make sure people at HashiCorp feel safe learning and making mistakes, be particularly careful when you have a strong negative reaction to something you’re asked to review. Consider drafting your feedback and waiting until the next day to re-read, and edit if needed, before you send. And if you have especially difficult feedback—for example, if you review an RFC that shouldn’t happen at all, which is rare but not unheard of—don’t respond in the document. Instead, reach out to the writer directly and discuss your concerns over Zoom.
I’ve learned not to send feedback, negative or otherwise, at the end of a week. If someone wanted to talk to me about it, they’d have to wait all weekend. I tend to read a lot of RFCs on Friday afternoons, but I schedule the feedback to go out Monday morning.
Finally, remember to focus your feedback not just on what you think should change, but on what you appreciate—including the effort the writer put in. While it’s important to avoid creating a “hero culture” and covering every RFC with praise, we should always make time to celebrate each other’s work and highlight the parts we like.
Next Steps: Writing and Beyond
Many of us at HashiCorp find our writing culture has made us less reliant on—and reduced our patience for—the long, circular conversations that so often plague meetings. While writing reduces the number of meetings, meetings are still useful in the decision-making process. Our documents are the artifact, not the full process itself. If you want to schedule a Zoom brainstorming session with your team before (or while) creating a PRD or RFC, you should! If there’s value in sharing that thought process with other members of the team, or recording it for future reference, create a document when you’re done.
Even as documentation becomes more commonplace across HashiCorp teams, we still finalize many decisions synchronously in meetings. Writing makes those decisions far more efficient: If everyone comes to a meeting already having read and commented on the same document, it’s much easier to get aligned.
I like to add an ‘options exploration’ step between the PRD and RFC, and sometimes that’s a meeting. We don’t want to move from articulating an idea to proposing a solution so quickly that we cut off ideation.
When the comments in a document aren’t converging on resolution, I go straight to Zoom. Sometimes, a five-minute call can clear up the disconnect.
And just as our team’s writing culture has evolved from blank Google docs to the processes we have today, they’ll continue to evolve as HashiCorp grows. For all the thought we’ve put into PRDs, RFCs, and the rest of our documents, there’s plenty of room for improvement, and no doubt we’ll keep making changes. We do believe, though, that the fundamentals are in place, and that our writing practices reflect the core principles of our company, from the humility to seek information from multiple sources to the vision to distill simplicity from complexity. When we were two, 10, and 100 people, we wondered whether our writing practices would scale. Now that HashiCorp has more than 1,000 employees and continues to grow, our writing culture remains a foundation for how HashiCorp works.
Templates, Tools, and Resources
For more guidance on how to write PRDs and RFCs, see the below resources.
How to write a PRD (internal)
PRD Template (public)
PRD Example:
How to write an RFC (internal)
RFC Template (public)
RFC Examples:
NMD-XXX Task Dependencies UI (internal)
Manager Charter (public)
SE-025: Standardized Customer Environment Documentation (internal)
Write in Plain Language course (internal)
Technical Writing Workshop (public)
