You Cant Write a Bad Requirements Document

Full text: 4,886 characters, reading time: 10 minutes

This is the legendary requirements‑document template mentioned in “Ten Sentences for Product Managers” (https://yuque.antfin.com/zhilan.zxw/gd9q0t/aelgtg), originally from my supervisor when I first became a product manager. Respectfully.
For the sake of clarity, I have made minor edits to the original: I replaced some company‑specific jargon with generic terms and updated the examples to familiar cases such as WeChat, Taobao, and Didi. The overall structure remains unchanged.
I hope everyone can produce a solid requirements document. Below is the full text.

The familiar has no scenery. As a product manager, you are so accustomed to the phrase “requirements document” that you can utter it without a second thought. Yet, no matter the request, a requirements document will bridge time and space, carrying your world‑changing idea to every reader’s mind. How you help them envision the future you see, how you enable the builders of that world—by “builders” I mean the engineers, if we’re not clear—to turn your ideal into reality without hesitation, and how you allow future teammates to stand on your shoulders and keep looking ahead—all depend on the document you write. From here on, let every line you write demonstrate your professionalism as a PM and make your team’s collaboration a pleasant experience. You can always find a way to make the world better because of you; that is the honor and dream of our era.

Change Log

No.	Change Date	Change Content	Changed By
1	2015-06-27	Created document	Your Name

From the moment you create a requirements document, you must fill out the change log for every modification—unless you’re merely fixing a typo. Use Heading 1 style for the “Change Date” text so the table of contents can capture the document hierarchy accurately. Dates must follow the YYYY‑MM‑DD format.
Tips: In the wiki, copied tables may contain an invisible space in empty cells; delete it when you type. (The wiki is Confluence, a shared‑document platform used by companies like Meituan and Didi.) Avoid full‑width punctuation such as “－”, “／”, “：”, etc.; use straight quotes for paired symbols. All timestamps should use YYYY‑MM‑DD and HH:MM:SS formats—pay attention to digit counts and separators. These formatting details should become habits; once they do, they’ll cost you no time but will make your document flawless. The rest of the guide will not repeat these points, nor this sentence itself.

1 Requirements Background

1.1 Current Situation

Answer the question “Why do we need this requirement?”

Readers of the requirements document may doubt the importance of the request or whether the proposed solution is optimal, so a precise problem definition helps others grasp your thinking.

Requirements can stem from many sources, including but not limited to:

• Rational sources
  • Data analysis
  • User research
  • User feedback (essentially a form of qualitative data analysis)
  • Management requests (when the manager can articulate a rational basis, we trust it)
• Emotional sources
  • Competitive‑product analysis / industry conventions
  • Product intuition

More formatting tips: Use hierarchical numbering such as “1”, “1.1”, “1.1.1” for headings. When updating the document, adjust the heading numbers accordingly. Apply Heading 1 style to “1 Requirements Background”, Heading 2 to “1.1 Current Situation”, and continue descending styles for deeper levels. Do not leave a leading space before any line of text. Insert two half‑width spaces between a heading number and its title. For body text, ensure paragraph spacing is larger than line spacing (press Enter to create a paragraph; the gap between two paragraphs is paragraph spacing, whereas the gap within a wrapped line is line spacing). Sometimes paragraph spacing may equal line spacing after pasting text—delete the extra line break and press Enter again to fix it.

1.2 Goal

Define “what method we will use and what effect we aim to achieve.”

The definition of “method” can be broad, as the “Requirements Overview” section will list concrete actions. The definition of “effect” requires more thought, because it determines whether you truly solved the problem described in the background.

If this is a temporary request that only addresses a short‑term issue, or if you adopted a stop‑gap solution to save time, explain your reasoning and outline when and how you plan to tackle the deeper problem later.

2 Expected Outcomes

Quantitatively describe the impact after the requirement is implemented. Quantification makes verification easier.

If you aim to “increase conversion rate” or “improve operational efficiency,” provide the following:

• Current conversion rate / operation time
• Expected conversion rate / expected operation time after rollout (and how you derived these numbers)
• Review point (when you will validate the improvement)

If precise numbers are hard to forecast, at least list the metrics you will monitor and the review timing.

If the goal is “enhance user experience in a certain area”—which is hard to quantify—list the affected user count and relevant usage frequency.

3 Requirements Overview

Priority	Feature / Improvement	Description
1	WeChat Home UI redesign
2	Add “collapse group chat” feature to group chats	iOS only for this release; Android will follow in the next version

List the functional or improvement points addressed by the requirement, answering “what needs to be done.” Example entries:

• WeChat Home UI redesign (consumer‑facing product)
• Add “collapse group chat” feature (consumer‑facing product)
• Add column‑header sorting to the “XXXX” page (enterprise product)
• Add permission control to the “Delete” function on the “XXXX” page (enterprise product)
  If a development cycle only covers part of the items in the list, note “Deployed on MMMM‑DD‑YY” in the Description column for items already released, and write “Not required for this release” for items that won’t be developed now.

4 Requirement Details

4.1 WeChat Home UI Redesign

The secondary headings in the “Requirement Details” section must correspond one‑to‑one with the items in the “Requirements Overview” table. If a single requirement contains multiple independent sub‑requirements, describe each separately, using third‑level or deeper headings as needed.

4.1.1 Overall Description

Besides a high‑level overview of the feature, a large requirement that spans several interaction steps should include a business flow diagram illustrating how users will use the feature and how the internal modules relate to each other.

Flow‑chart advice: Use concise, clear diagrams to convey business logic. Not every detail needs a diagram; identify the parts most prone to misunderstanding and clarify them appropriately. A flowchart should show the main flow and any branching paths (this is important elsewhere in the document as well). Unless there is only a single operator, label each step with the responsible role.

4.1.2 Module Descriptions

4.1.2.1 Module 1

4.1.2.2 Module 2

4.1.2.3 Module 3

Before describing each module, attach its prototype. Even if the visual design is not final, provide a layout that clearly shows page structure, interactive controls, placeholder text, etc. (The same applies to backend requirements.)

Prototype tip: Prototypes are crucial for conveying ideas. Pay attention to size, font, color, layout, and alignment for every component. Before sharing, ensure the text in the prototype is realistic and that each element can be referenced by a numbered label, so readers can quickly locate the relevant area while reading the document. If a prototype page is long or complex, you may insert a zoomed‑in excerpt in the appropriate textual section.

4.2 Taobao Item “Add to Favorites” Feature

4.2.1 Overall Description

4.2.2 Add Favorites on List Page

4.2.3 Add Favorites on Detail Page

4.2.4 “My Favorites” List

For each requirement, first ask yourself whether it is the best solution, not just how clearly you can describe it.

When a PM proposes a solution, the user may only see a fragment of it; many surrounding questions belong in the requirement itself. For example, if you want to display a Didi driver’s order count, you must also specify how to obtain that data and ensure its authenticity. Likewise, if you intend to list all Didi drivers, the sorting strategy is part of the requirement—not merely “show the drivers.”

Since this is a template, we’ll focus on description. Keep the following points in mind when writing:

• For every interactive element on a page (banner, button, input field, dropdown, etc.), provide a complete description of its behavior and style:

  • Control type (radio button, checkbox, dropdown, text field, etc.)
  • Interaction effect (e.g., loading animation when navigating to a new page, a modal that appears after a click, tooltip on hover, etc.)
  • Default content / default option (e.g., pre‑filled text in a field, placeholder gray text when empty)
  • Validation logic (e.g., must enter a phone number—explain how to determine a valid phone number, character limits, etc.)
  • Availability constraints (e.g., a button disabled under certain conditions, a field hidden in specific scenarios)

• Consider edge cases beyond the main flow, including but not limited to:

  • Violations of validation rules (e.g., user enters Chinese characters in a numeric field, exceeds allowed range, leaves a required field blank) and the system’s error feedback.
  • Poor network conditions: how long to wait before timing out, what message to show, etc.
  • For app‑based requirements, define which data should be cached for offline or low‑signal usage.
  • Page navigation failures due to network issues: stay on the new page, revert to the previous page, and which parts of the new page must be available offline.
  • List pagination: need for lazy loading, items per page, pagination controls, loading behavior (auto‑load on scroll, pull‑to‑refresh, button click, etc.).
  • Page refresh mechanisms: pull‑to‑refresh, periodic auto‑refresh, etc.
  • Image loading strategy: caching or lazy loading to improve speed and save bandwidth.

Overall, write the document as if the reader knows nothing about the requirement; continually check that the description is clear and unambiguous.

5 Statistical Requirements

Define which user actions must be tracked to verify the metrics described in the Expected Outcomes section (and any other metrics of interest). As with the “Requirement Details” section, specify the data to be collected precisely so readers understand exactly what you need.

If there are no statistical requirements, still create this top‑level heading and fill it with:

This requirement does not include any statistical tracking.

6 Research Process

As a supplement to the background, list any data analyses, user research, or feedback collection you performed before raising the requirement.

If no research was conducted, still create this heading and fill it with:

The formulation of this requirement did not involve data analysis or user research.

7 Implementation Plan

Create a sub‑page named “XXXX Implementation Plan” (replace XXXX with the requirement name). Each requirement can have its own sub‑page, or you can consolidate them into a single document. The responsible engineer should author and maintain this page.

---

WeChat Official Account: A Product Dog’s Confession
Sharing product insights, reflections, and reading notes.

Scan the QR code to follow. Thanks!

---

Originally written by Estela Young and published in Chinese on 一只产品汪的自白. Translated and edited for DriftSeas with permission.