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.
Use a comma to join two independent clauses which are separated by a conjunction such as and, or, nor, but, for, so, yet. Insert the comma after the first clause, that is before the conjunction. Don’t insert a comma if both the clauses are very short. Likewise, consider rewriting the sentence if it is long and complex.
Examples
Not recommended: Copy the file, and continue.
Recommended: Copy the file and continue.
Not recommended: Either download a theme suiting your needs or use one from the preinstalled themes.
Recommended: Either download a theme suiting your needs, or use one that is preinstalled.
Note: Don’t use a comma to join independent clauses when you don’t use a conjunction. Use a semicolon instead.
When an independent and dependent clause are separated by a coordinating conjunction, insert a comma only if the sentence could be misunderstood without one.
Examples
Not recommended: Pages can be password protected and can only be modified by administrators.
Recommended: Pages can be password protected, and can only be modified by administrators.
Not recommended: Permalinks are permanent URLs, and their structure can be changed.
Recommended: Permalinks are permanent URLs and their structure can be changed.
Use a comma to separate two or more adjectives that precede a noun that is being described. Only insert a comma if the meaning of the adjectives doesn’t change by separating the adjectives with and or reversing the order of them.
Examples
Recommended: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/ is a new, intuitive 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.
Not recommended: This is an enhanced, mobile UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing..
Recommended: This is an enhanced mobile UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing..
Rewrite sentences for a conversational style and tone if possible.
Examples
Sometimes okay: Write accessible, inclusive documentation.
Recommended: Write documentation that is accessible and inclusive of all readers.
Don’t insert a comma between verbs in a compound predicate. A compound predicate is when two or more verbs pertain to a single subject.
In general, rewrite a compound predicate in two sentences, or add a subject for the second verb.
Examples
Not recommended: The application parses the data, and displays it in the terminal.
Recommended: The application parses the data. Then it displays the data in the terminal.
Recommended: The application parses the data, and then it displays the data in the terminal.
