Source: https://developers.google.com/style/prescriptive-documentation\n\n# Prescriptive documentation
Stay organized with collections
Save and categorize content based on your preferences.\n\n- Home\n- Products\n- Style\n\n\n## Page Summary\n\n- Prescriptive documentation provides direct guidance by recommending specific actions and paths to achieve goals, rather than presenting multiple options.\n- The structure, examples, and procedures in prescriptive documents are tailored to the most relevant use cases and reader needs.\n- When writing prescriptive documentation, the words "must," "can," and "might" are used to indicate required, optional, or possible actions/outcomes respectively, whereas "should" is generally avoided due to its ambiguity.\n- To make actions clear, writers should use imperatives for required steps, or employ phrases like "We recommend" for suggested actions.\n- When describing a state or outcome, prescriptive documentation should use precise language that conveys whether the state is actual or required and the outcome is expected or possible.\n\nPrescriptive documentation provides direct guidance by recommending specific actions and paths to achieve goals, rather than presenting multiple options.\n\nThe structure, examples, and procedures in prescriptive documents are tailored to the most relevant use cases and reader needs.\n\nWhen writing prescriptive documentation, the words "must," "can," and "might" are used to indicate required, optional, or possible actions/outcomes respectively, whereas "should" is generally avoided due to its ambiguity.\n\nTo make actions clear, writers should use imperatives for required steps, or employ phrases like "We recommend" for suggested actions.\n\nWhen describing a state or outcome, prescriptive documentation should use precise language that conveys whether the state is actual or required and the outcome is expected or possible.\n\nWrite prescriptive documentation.\n\nPrescriptive (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.\n\nPrescriptive writing affects several aspects of documentation:\n\n- The purpose and structure of a document. Prescriptive documentation states a clear,
specific purpose. Headings and content are written with that purpose in mind.\n- Example scenarios and procedures. Scenarios and procedures reflect the use cases that
are most likely relevant to the readers.\n- 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.\n\nFor instance, best practice documents are typically prescriptive documents. For an example, see
Operations best practices.\n\n\n## Word choice for recommendations and requirements\n\nTo 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.\n\nTo 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.\n\n- 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."\n- 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 ...."\n- If an action is optional: use can. For example,
"You can also use approach B to solve the same problem."\n- If an outcome is expected: describe the outcome in terms of
what is expected. For example: "The process returns 10 items."\n- If an outcome is possible: use might or can.
For example, "The process can take about 30 minutes."\n- 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.\n- "You must set the value to true."\n- "The server sets the value to true."\n- "If the value is false, follow these steps to change it to true."\n\n- "You must set the value to true."\n- "The server sets the value to true."\n- "If the value is false, follow these steps to change it to true."\n\nFor information about clarifying who's performing an action, see
Active voice.\n\nRecommended: Ensure that the
Classroom Share Button conforms to our min-max size guidelines and related
color/button templates.\n\nRecommended: The column of the data
table that the filter operates on.\n\nRecommended: Whether it's a brand new
project or an existing one, perform the following steps.\n\nNot recommended: The Classroom Share
Button should conform to our min-max size guidelines and related color and
button templates.\n\nNot recommended: The column of the
data table that the filter should operate on.\n\nNot recommended: Whether it's a brand
new project or an existing one, here's what you should do.\n\n\n## More resources\n\n- See also can, could,
may, might,
must, and would in the
word list.\n