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. 

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. 

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. 

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.

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 templateto 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.

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.

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.

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.

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.

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?”

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.

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.

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:

• [PRD] TF-027: Terraform Integration w/ ServiceNow Service Catalog (internal)

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)