Source: https://developers.google.com/style/procedures\n\n# Procedures
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- Procedures should be written as numbered steps with clear and concise language, focusing on the action to be performed.\n- Sub-steps and multi-action steps have specific formatting guidelines to ensure clarity and readability, such as using letters and roman numerals for sub-steps and the > symbol for sequential actions within a single step.\n- Multiple procedures for the same task should be organized thoughtfully, prioritizing accessibility and clarity by using separate sections or tabs and favoring the shortest and simplest method.\n- Steps should provide context, clearly state the goal or purpose, and include any necessary justifications or results while avoiding redundancy and unnecessary information.\n- Optional steps are indicated with "Optional:", and repetitive procedures are referenced rather than repeated to maintain conciseness and avoid redundancy.\n\nProcedures should be written as numbered steps with clear and concise language, focusing on the action to be performed.\n\nSub-steps and multi-action steps have specific formatting guidelines to ensure clarity and readability, such as using letters and roman numerals for sub-steps and the > symbol for sequential actions within a single step.\n\nMultiple procedures for the same task should be organized thoughtfully, prioritizing accessibility and clarity by using separate sections or tabs and favoring the shortest and simplest method.\n\nSteps should provide context, clearly state the goal or purpose, and include any necessary justifications or results while avoiding redundancy and unnecessary information.\n\nOptional steps are indicated with "Optional:", and repetitive procedures are referenced rather than repeated to maintain conciseness and avoid redundancy.\n\nA procedure is a sequence of numbered steps for accomplishing a task. For information about
lists of items that aren't part of a procedure, see the
Lists page.\n\n\n## Introductory sentences\n\nIn most cases, introduce a procedure with an introductory sentence. This
introductory sentence should provide context to the reader that isn't part of
the section heading. Don't simply repeat the heading: if the heading explains
what the procedure is, and no additional context is needed, then don't
include an introductory statement.\n\nThe sentence can end with a colon or a period. Use a colon if it immediately
precedes the procedure. Use a period if there's more material (such as a
note paragraph) between the introduction and the procedure.\n\nYou can introduce a procedure with an imperative statement. Don't introduce a procedure with
a partial sentence that's completed by the numbered steps.\n\nRecommended: To customize the buttons,
follow these steps:\n\nAlso recommended: Customize the buttons:\n\nAlso recommended: To customize the buttons, do the following:\n\nNot recommended: To customize the
buttons:\n\nFor more information about introducing lists, see Lists.\n\n\n## Single-step procedures\n\nWhen a procedure consists of only one step, write the step in one sentence and format it as a
bulleted list.\n\nRecommended:\n\n- To clear (flush) the entire log, click Clear logcat.\n\nNot recommended:\n\nTo clear (flush) the entire log, follow this step:\n\n- Click Clear logcat.\n\nAlso not recommended:\n\nTo clear (flush) the entire log, follow this step:\n\n- Click Clear logcat.\n\n\n## Sub-steps in numbered procedures\n\nIn a numbered procedure, sub-steps are labeled with lowercase letters, and
sub-sub-steps get lowercase Roman numerals.\n\nWhen a step has sub-steps, treat the step like an introductory sentence: put a colon or a
period at the end of the step, as appropriate.\n\nFor more information about lists, see Lists.\n\nRecommended:\n\n- To add a VM instance, do the following:
Click Create instance.
For Name, enter a name for the VM instance, and then do the following:
For Region, specify where you want to deploy the VM instance.
For Machine type, select an option.
Click Create.\n- Click Create instance.\n- For Name, enter a name for the VM instance, and then do the following:
For Region, specify where you want to deploy the VM instance.
For Machine type, select an option.\n- For Region, specify where you want to deploy the VM instance.\n- For Machine type, select an option.\n- Click Create.\n- To connect to the VM instance by using SSH, click SSH.\n\n- Click Create instance.\n- For Name, enter a name for the VM instance, and then do the following:
For Region, specify where you want to deploy the VM instance.
For Machine type, select an option.\n- For Region, specify where you want to deploy the VM instance.\n- For Machine type, select an option.\n- Click Create.\n\n- For Region, specify where you want to deploy the VM instance.\n- For Machine type, select an option.\n\n\n## Order of multiple components in a step\n\nTo document a complex procedural step, use the following order:\n\n- Describe the action to take.\n- List a command, if necessary.\n- Explain any placeholders that are used in the command.
For more information, see
Formatting placeholders.\n- Explain the command in more detail, if necessary.\n- List the output of the command, if necessary.
For more information, see
Output from commands.\n- In a separate paragraph, explain
the result of an
action, or any output, if necessary.\n\nExplain any placeholders that are used in the command.\n\nFor more information, see
Formatting placeholders.\n\nList the output of the command, if necessary.\n\nFor more information, see
Output from commands.\n\nThe following example demonstrates the preceding order:\n\n- Plan the Terraform deployment:
terraform plan -out=NAME
Replace NAME with the name of your Terraform plan.
The terraform plan command does the following:
Parses the Terraform configuration, building a list of resources to provision.
Refreshes the current state of resources already provisioned in Google Cloud.
Creates a plan to make the currently provisioned resources match the parsed
configuration.
The output is similar to the following:
Plan: 26 to add, 0 to change, 0 to destroy.
This plan was saved to: NAME
The output shows what resources to add, change, or destroy.\n- Parses the Terraform configuration, building a list of resources to provision.\n- Refreshes the current state of resources already provisioned in Google Cloud.\n- Creates a plan to make the currently provisioned resources match the parsed
configuration.\n\nPlan the Terraform deployment:\n\n``\nterraform plan -out=NAME\n``\n\nReplace NAME with the name of your Terraform plan.\n\nThe terraform plan command does the following:\n\n- Parses the Terraform configuration, building a list of resources to provision.\n- Refreshes the current state of resources already provisioned in Google Cloud.\n- Creates a plan to make the currently provisioned resources match the parsed
configuration.\n\nThe output is similar to the following:\n\n```\nPlan: 26 to add, 0 to change, 0 to destroy.
This plan was saved to: NAME\n```\n\nThe output shows what resources to add, change, or destroy.\n\n\n## Multi-action procedures\n\nIn general, use one step for each action. However, you can combine small actions
into one step by using
angle brackets (>) for sequential menu selections.\n\nRecommended:\n\n- Click Next > Finish.\n\nAlso recommended:\n\n- Click
File > New > Document.\n\nDon't make the steps too long. If they feel too long, consider splitting them
into multiple steps.\n\n\n## Multiple procedures for the same task\n\nIn general, if there's more than one way to complete a task, then document
one procedure that's accessible for all readers. If all methods are accessible, pick the shortest
and simplest approach if possible. If you need to document multiple ways to complete a
task, then separate them in different pages, headings, or tabs.\n\nThe following guidelines can help you choose which procedure to document:\n\n- Choose a procedure that lets readers do all the steps by using only a keyboard.\n- Choose the shortest procedure.\n- Choose a procedure that uses a programming language that most of your
audience is familiar with.\n\n\n## Repetitive procedures\n\nAvoid repeating procedures. Instead, reference those procedures and link to
them.\n\nRecommended:\n\n- Create a user as you did in the previous step.\n\nAlso recommended:\n\n- Create a user as you did in the previous step.\n\n\n## Optional steps\n\nFor an optional step, at the beginning of the step, type Optional
followed by a colon.\n\nRecommended:\n\n- Optional: Type an arbitrary string ...\n\nNot recommended:\n\n- (Optional) Type an arbitrary string ...\n\n\n## Steps that say where to complete a task\n\nTell the reader where to complete an action—for example, in a
particular tool or UI field—before you state the action.\n\nRecommended:\n\n- In Google Docs, click
File > New > Document.\n- In the Google Cloud console, go to the Monitoring page.\n\nNot recommended:\n\n- Click File >
New > Document in Google
Docs.\n- Go to the Monitoring page in the Google Cloud console.\n\nIf a set of procedures is split across multiple headings, then in each
procedure, restate where the reader completes the action. For example, if two
procedures in a document take place in the console, then start both
procedures with "In the console ..."\n\n\n## Steps with goals\n\nFor some steps, it's useful to state the goal
that the step accomplishes.\n\nWhen a step includes a goal, state the goal before the action. This
structure helps readers understand and complete the step more easily.\n\n- To start a new document, click
File >
New > Document.\n\n- Click File >
New > Document to start a
new document.\n\nSometimes, the preceding format can imply that the required step is
optional. In such cases, use the following format:\n\nRecommended:\n\n- Start a new document: click
File >
New > Document.\n\nIt's usually clear within the context of a procedure whether a step is
required. In such cases, the "To ..." format is more natural than the colon
format.\n\nTo determine whether you need to use the colon format, consider how the
goal of the step relates to the goal of the procedure. For example, in a
procedure for creating a bar chart, a step with the goal "To create the
chart" is clearly required. A step with the goal "To enhance the chart" is
also unlikely to create confusion. But a step with the goal "To sort the
data by date" might or might not be necessary. To clarify that the step
isn't optional, use "Sort the data by date:" instead.\n\n\n## Steps with results or justifications\n\nSome steps consist of an action along with a resulting reaction that helps
the reader navigate to the next step. State the action first and the result
second. Keep the result in the same paragraph as the action. But also consider whether you
can avoid repetitiveness and overwhelming the reader with too much bolding of UI elements.\n\n- Click Run. The query results appear after the query runs.\n\n- Click Enter.\n- In the New file dialog that appears, click Next.\n\n- Click Enter. The New file dialog appears.\n- In the New file dialog, click Next.\n\nFor information about describing output, see
Output from commands.\n\nOther steps benefit from including a justification for why the step is
important. State the action first and the justification second.\n\n- Store the private key in a secure location. You need it later.\n\n\n## Summary of guidelines for writing procedures\n\n\nGuidance | Recommended | Not recommended\nMake sure that the first sentence in a procedural step includes an imperative verb. | Clone the repository that contains the sample data. | You need the project ID later in this document. Retrieve the project ID.\nUse complete sentences. | | \nUse parallel structure and consistent verb form. | Download the service account key to
your local machine. Click More, and then click Download. | Download the service account key to your
local machine by clicking More and then clicking Download file.\nFor an optional step, type Optional: as the first word of the step. | Optional: Type an arbitrary string... | (Optional) Type an arbitrary string...\nSet the context (such as a tool or an environment) in which the reader performs a
procedure.
If there are multiple headings associated with a set of procedures, restate the context
of the procedure in the first step, even if the context is the same as in the previous
procedure. | In Cloud Shell, connect to the development cluster.
In the Google Cloud console, go to the BigQuery page. | \nWrite in the order that the reader needs to follow. State the location of the action
before stating the action. | In Google Docs, click File >
New > Document.
In the Google Cloud console, go to the Monitoring page. | Click File >
New > Document in Google Docs.
Go to the Monitoring page in the Google Cloud console.\nState the purpose or goal of the action before stating the action. | To start a new document, click File >
New > Document. | Click File >
New > Document
to start a new document.\nDon't use directional language to orient the reader, such as above, below,
or right-hand side. This type of language doesn't work well for accessibility or for
localization. If a UI element is hard to find, provide a screenshot.
For information about documenting icons, see
Buttons and icons. | Click menuMenu.
In the preceding diagram,...
In the following diagram,... | Click the button with three lines.
In the above diagram, ...
In the diagram below, ...\nDon't use please. | To open a document, click File > Open. | To open a document, please click
File > Open.\nAvoid using run the following command to introduce code. Instead, focus on what
the command does. | In Cloud Shell, deploy the load generator:...
Define a firewall rule to allow internal traffic:... | In Cloud Shell, deploy the load generator by running the following command:...
Run the following command:...\nIf the reader must press Enter after a step, then include that instruction as part
of the step. | Click the search box, type custom function, and then press Enter. | Click the search box and type custom function.
Press Enter.\nDon't include keyboard shortcuts. | Copy the command, and then paste it... | Press Ctrl+C, and then press Ctrl+V...\nWhen there's more than one way to do something, give only the best way. Giving alternate
ways can confuse readers. | | \nIf your procedure includes code samples, see how to format code samples. | | \nIf your procedure includes commands, see how to format commands. | | \nEnsure that the reader has the information that they need in order to prepare for the
task ahead of time. Having information in advance supports task management, executive
functioning, memory, and emotional regulation. | The following hardware and software are required:... | \nInclude as few steps as possible to complete the task. Limit interruptions in the path. | | \nFocus on one reader decision at a time. Separate each instruction by making each
instruction a separate list item. | | \n\nSet the context (such as a tool or an environment) in which the reader performs a
procedure.\n\nIf there are multiple headings associated with a set of procedures, restate the context
of the procedure in the first step, even if the context is the same as in the previous
procedure.\n\nIn Cloud Shell, connect to the development cluster.\n\nIn the Google Cloud console, go to the BigQuery page.\n\nIn Google Docs, click File >
New > Document.\n\nIn the Google Cloud console, go to the Monitoring page.\n\nClick File >
New > Document in Google Docs.\n\nGo to the Monitoring page in the Google Cloud console.\n\nDon't use directional language to orient the reader, such as above, below,
or right-hand side. This type of language doesn't work well for accessibility or for
localization. If a UI element is hard to find, provide a screenshot.\n\nFor information about documenting icons, see
Buttons and icons.\n\nClick menuMenu.\n\nIn the preceding diagram,...\n\nIn the following diagram,...\n\nClick the button with three lines.\n\nIn the above diagram, ...\n\nIn the diagram below, ...\n\nAvoid using run the following command to introduce code. Instead, focus on what
the command does.\n\nIn Cloud Shell, deploy the load generator:...\n\nDefine a firewall rule to allow internal traffic:...\n\nIn Cloud Shell, deploy the load generator by running the following command:...\n\nRun the following command:...\n\n- Click the search box and type custom function.\n- Press Enter.\n