Welcome to the official home of the WordPress Documentation Team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.
Want to get involved?
Start here to find out more about what we do and how to contribute:
Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Weekly meetings
Join our discussions of documentation issues here on the blog and on Slack.
Highlight: Use procedures to provide a sequence of numbered steps or instructions for achieving a particular task.
A procedure is a sequence of numbered steps or instructions for achieving a particular task. Procedures can be presented in various formats such as illustrations, infographics, videos, single-step instructions, and numbered procedures.
For more information about lists of items that aren’t part of a procedure, see Lists.
For more information about expressing UI elements, see UI elements and interaction.
In most cases, introduce a procedure with an introductory sentence that initiates the procedure that follows. If the heading of the content explains what the procedure is about, and no additional context is required, then don’t include an introductory statement. You can introduce a procedure with an imperative statement.
The introductory sentence can end with a colon or a period. Use a period if the introductory content is extended, and a colon if the introductory statement is shorter and immediately precedes the procedure. The text preceding the colon must distinctly stand alone as a complete sentence. That is, don’t introduce a procedure with a partial statement.
Examples
Not recommended: To change the settings:
Recommended: To change the settings, follow these steps:
Recommended: Change the settings:
Not recommended: The settings are:
Recommended: The settings that can be changed are as follows:
In numbered procedures, label sub-steps with lowercase letters, and sub-sub-steps with lowercase Roman numerals.
When a step has sub-steps, write the step as an introductory statement to the sub-steps.
Example
Recommended:
1. To set up your development environment, follow these steps:
a. Install Node development tools as follows:
i. Download and install Node Version Manager (nvm). sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
ii. Quit and restart the terminal. sh
nvm install --lts
b. Set up your WordPress environment:
i. Download, install, and start Docker Desktop following the instructions for your OS.
ii. Install the WordPress environment tool. sh
nvm install --lts
iii. Start the environment from an existing pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party or theme directory, or a new working directory: sh
wp-env start
c. Set up your code editor.
In general, use one step per action. However, you can combine multiple small actions into a single sequential step using angle brackets (>) to make simple sentences. Insert a nonbreaking space ( ) around each bracket, and enclose the entire sequence in a single bold element. For more information, see Menu bar
Examples
Recommended: 1. Go to Settings > Media.
Recommended: 1. Go to Edit > Text > Encoding.
Caution: Screen readers may skip over brackets and may not read them as intended. For example, Settings > Media may be read as Settings Media, which might confuse readers. Analyze with an accessibilityAccessibilityAccessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) expert before implementing this approach.
Avoid making long sequential steps. Consider rewriting them by splitting them into sub-steps if they get complicated.
Format procedures consistently so that readers know where to find them easily by scanning content.
In general, use headings for procedures so that readers find the exact instructions quickly. Write the heading such that it describes what the instructions will help the readers do. Examples
Recommended: Create a new page
Recommended: Edit your post
Capitalize the first word in each step and end the step with a period; except where the step doesn’t include end punctuation.
Write complete sentences with a consistent sentence structure. Use a standard writing style for headings and instructions in procedures.
Individually number each step in a procedure. It is acceptable to combine short steps that occur in the same place in the UI.
State the purpose of the actions before stating the action. Examples
Not recommended: Click Save Changes to save the modified file.
Recommended: To save the modified file, click Save Changes.
Write the instructions in the order that the reader needs to follow. State the location of the action before stating the action. If there are multiple sets of procedures with steps and sub-steps, restate the location of the action in the first step of the procedure. Examples
Not recommended: Click Settings > Media after navigating to the task menu bar.
Recommended: Navigate to the task menu bar, then click Settings > Media.
It is acceptable to not provide context such as UI element position multiple times within a step, if the instruction appears in the same UI where the action occurs.
If a particular step is optional in a procedure, indicate it by mentioning “Optional” at the beginning of the step. Example
Recommended: Optional: If docker is not running, try to restart the service using: sh
sudo systemctl daemon-reload
sudo systemctl restart docker.service
If you think that a specific step might confuse the reader, provide an introductory step. You can also include a brief phrase so that the reader follows the instruction at the right place. Example
Recommended: Navigate to the menu bar and click on the Encoding tab.
When there is more than one way to achieve a particular task, give the best way to do so. Multiple alternative procedures can confuse readers.
In general, avoid using directional language such as left, right, up, down in instructions to locate UI elements or other content. People with cognitive impairments, as well as people using assistive technologies such as screen-reading software and might have difficulty interpreting directional language. Directional language proves to be difficult for accessibility or for localization. If a particular UI element or other content is difficult to convey, include a screenshot or illustration. Examples
Not recommended: On the upper-right part of the page, click the button with the checkmark.
Recommended: Click ✓ Publish.
Don’t include keyboard shortcuts in instructions.
Most of the time, end procedures with a definite action or result that helps the reader achieve that particular task.
