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](https://developers.google.com/style/code-syntax#click-to-copy-commands).

For instance, best practice documents are typically prescriptive documents. For an example, see
[Operations best practices](https://cloud.google.com/architecture/security-foundations/operation-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](https://developers.google.com/style/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

- See also [can](https://developers.google.com/style/word-list#can), [could](https://developers.google.com/style/word-list#could), [may](https://developers.google.com/style/word-list#may), [might](https://developers.google.com/style/word-list#might), [must](https://developers.google.com/style/word-list#must), and [would](https://developers.google.com/style/word-list#would) in the word list.