Welcome to the official home of the WordPress documentation team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of developer.wordpress.orgWordPress.orgThe community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, admin help, inline docs, and other general wordsmithing across the WordPress project.
Want to get involved?
There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:
Block Editor Handbook: An overview of documentation contributions of BlockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor / GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/
Documentation Issue Tracker on GitHub: Submit any DevHub/HelpHub/”Doc Team Handbook” Docs-related issue 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/.
Join our discussions of documentation issues here on the blog and on Slack.
Note: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.
Warning:Not recommended: To change the settings:
Tip:Recommended: To change the settings, follow these steps:
Tip:Recommended: Change the settings:
Warning:Not recommended: The settings are:
Tip:Recommended: The settings that can be changed are as follows:
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
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
Tip:Recommended: 1. Go to Settings > Media.
Tip:Recommended: 1. Go to Edit > Text > Encoding.
Alert: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.
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
Warning:Not recommended: Click Save Changes to save the modified file.
Tip: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
Warning:Not recommended: Click Settings > Media after navigating to the task menu bar.
Tip: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
Tip: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
Tip: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
Warning:Not recommended: On the upper-right part of the page, click the button with the checkmark.
Tip: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.