Prescriptive documentation

Write prescriptive documentation.

Prescriptive (or opinionated) documentation recommends a way to achieve tasks and accomplish goals. It tells the reader what to do instead of giving them a list of options to choose from. When a goal or task is complex and involves multiple approaches or products, prescriptive documentation recommends a path.

Prescriptive writing affects several aspects of documentation:

  • The purpose and structure of a document. Prescriptive documentation states a clear, specific purpose. Headings and content are written with that purpose in mind.
  • Example scenarios and procedures. Scenarios and procedures reflect the use cases that are most likely relevant to the readers.
  • Sample commands. Prescriptive documentation provides commands and arguments that accomplish the task for the most common use case. For more information about documenting command-line options, see Optional arguments in click-to-copy commands.

For instance, best practice documents are typically prescriptive documents. For an example, see Operations best practices.

Word choice for recommendations and requirements

To indicate required or optional user actions or the outcomes of a process, select an appropriate auxiliary verb—for example, must, can, or might. Generally avoid the word should. The word can create ambiguity and uncertainty for readers and is thus problematic for prescriptive documentation. For example, if you're telling the reader what to do, should implies that the action is recommended but optional, which can leave the reader unsure about what to do.

To clarify what you mean, determine if an action is required versus optional, an outcome is expected versus possible, or a state is actual versus recommended.

  • If an action is required: use must, or rephrase the sentence so that it's a clear imperative instruction such as "Do the following before you continue."
  • If an action is recommended: use We recommend ... or Google recommends .... You can use should if a recommended action is generally recognized. For example, "You should use a strong password ..." or "You should follow the principle of least privilege ...."
  • If an action is optional: use can. For example, "You can also use approach B to solve the same problem."
  • If an outcome is expected: describe the outcome in terms of what is expected. For example: "The process returns 10 items."
  • If an outcome is possible: use might or can. For example, "The process can take about 30 minutes."
  • If a state is actual: when you're describing the state of something, such as the value of a variable, avoid writing "The value should be true." Instead, clarify which of the following you mean:
    • "You must set the value to true."
    • "The server sets the value to true."
    • "If the value is false, follow these steps to change it to true."

    For information about clarifying who's performing an action, see Active voice.

Recommended: Ensure that the Classroom Share Button conforms to our min-max size guidelines and related color/button templates.

Recommended: The column of the data table that the filter operates on.

Recommended: Whether it's a brand new project or an existing one, perform the following steps.

Not recommended: The Classroom Share Button should conform to our min-max size guidelines and related color and button templates.

Not recommended: The column of the data table that the filter should operate on.

Not recommended: Whether it's a brand new project or an existing one, here's what you should do.

More resources