[PRD] Confusing widget creation workflow
Summary: Community members struggle to finish the final step in releasing widgets.
|Status: (WIP, In Review, Approved, Obsolete)|
|RFC: (Link to RFC when created)|
The Problem Requirements Document (PRD) begins with a brief introduction that explains the goal of the PRD. While the introduction section is read first, it should be authored last. Writing the overview last allows the author to summarize the final content of the PRD, rather than write an introduction without knowing the end result.
The goal of the background section is to provide the reader with helpful context before diving into the problem domain. Provide sufficient details to properly educate the reader on the problem domain. In order for a reader to understand the content of the PRD, they must first understand the context. That context setting is the goal of the background section. Visual explanations are encouraged if applicable.
This is the heart of the PRD as it simplifies the user research into clear problem statements. Each of the problems should clearly map to the problems identified by the user research and the corresponding personas defined below. The personas should be generalized versions of the actual interviewed users.
The problem is broken down into phases to enable iterative implementation. Each phase:
Some PRDs will only have one phase; that is completely fine.
The title defines the objective for solving the problem and references the persona (e.g. “Must be easier for policy writers to create Terraform mock data for sentinel tests”).
While each phase focuses on a single problem from the users perspective, it may need to be broken down into multiple requirements to address specific problems with individual components, features, docs, etc. There are a few things to consider when writing the requirement:
The acceptance criteria should be written like test cases for the requirement. This should be written objectively so anybody can validate the criteria is met prior to release.
Each requirement should have a “Considerations” section which is a consideration for the RFC writer. It should almost always be a question, not a suggestion. They could be dismissed outright or answered within the RFC to call back to the consideration itself. During the review process it is likely that most comments will target the considerations; in most cases these comments will need to be deflected to the RFC.
This section is the most important as it grounds the PRD in real, experienced user problems. For the author the goal of this section is to collect high-quality research which will be used to identify common patterns across users. The better the research, the easier it is to determine patterns, and the simpler the problem statement can be. For readers this section sets a concrete context for understanding the core problem.
For each customer include a link to the interview notes, a short paragraph explaining the state of their workflow today, and key takeaways
Red names still require approval, green names with a checkmark have approved.
Each of the representative stakeholders must approve the PRD before it proceeds to kick-off and RFC writing. Sign-off by stakeholders requires these to be satisfied:
Approved names will have a ✅
Project Engineering Lead:
VP of Product:
Sales Engineer Lead:
[Add other approvers as necessary]
All PRDs should follow similar styling and structure to ease reading. "Beautiful is better" is a core principle of HashiCorp and we care about the details.
"Heading 2" should be used for section titles. We do not use "Heading 1" because aesthetically the text is too large. Google Docs will use Heading 2 as the outermost headers in the generated outline.
"Heading 3" should be used for sub-sections.
Further heading styles can be used for nested sections.
When making lists, it is common to bold the first phrase/sentence/word to bring some category or point to attention. For example, a list of API considerations:
Type size should use this template's default configuration (11pt for body text, larger for headings), and the type family should be Arial. No other typeface customization (eg color, highlight) should be made other than italics, bold, and underline.
Code samples should be indented (tab or spaces are fine as long as it is consistent) text using the Courier New font. If syntax highlighting is included, please ensure the highlighted syntax is the proper font size and using Courier New font so non-highlighted samples aren't out of place.
CLI output samples are similar to code samples but should be highlighted with the color they'll output if it is known so that the RFC could also cover formatting as part of the user experience.