Documentation Grammar Guide

Note: This is a draft version and we’re looking to improve it with community feedback.

General General

Use American English spelling (-ize and -or, not -ise and -our).

Write in the active voice whenever possible.

When referring to either the block editor or the classic editor, qualify the editor the first time (block editor or classic editor), then use editor by itself after that.

With the verb log in, the correct preposition is to. Write log in to, not log into.

Write homepage as one word (not home page).

Top ↑

Quotation Marks Quotation Marks

Do not use quotation marks for emphasis. Phrases in quotation marks may be interpreted by readers as irony or sarcasm.

Similarly, do not use quotation marks to indicate a command or something the user needs to type. The user may mistakenly assume the quotation marks are part of the command. Instead, use backticks (`) to create an inline code block: npm install react.

Quotation marks should be used only for direct quotes and the titles of documents.

Top ↑

Capitalization Capitalization

Always capitalize WordPress (and remember to capitalize the P).

Capitalize Classic Editor when referring to the plugin. Do not capitalize it otherwise (classic editor).

Capitalize the names of pages, links, plugins, and buttons (the Save button, the Posts page). 

Do not capitalize regular nouns, including WordPress elements: theme, plugin, page, block, user, administrator. 

Do not capitalize a word just to add emphasis to it. Instead, place it in boldface or italics.

Top ↑

Hyphenation Hyphenation

In general, don’t hyphenate compound adjectives unless it clears up ambiguity or makes the sentence more readable (small-business owner but open source software). 

Do not hyphenate compounds with an adverb ending in -ly (a nicely formatted document).

Hyphenate the adjectives back-end and front-end (a back-end developer). Note that the nouns are back end and front end.

Do not hyphenate login. Note that login is a noun or adjective; the verb is log in (Go to the login page to log in).

Top ↑

Lists Lists

Use a colon (:) to introduce a list when it is preceded by a full sentence. Do not use a colon otherwise, even if you are introducing a bulleted list. It can interrupt the flow of reading.

Correct

The following basic options are supported by this plugin: order, orderby, and column_id.

This plugin supports the order, orderby, and column_id options.

Incorrect

The following basic options are supported by this plugin, order, orderby, and column_id.

The options this plugin supports are: order, orderby, and column_id.

Top ↑

Oxford Comma Oxford Comma

Use the Oxford comma, which means including the final comma before and or or in a list: apples, oranges, and bananas.

Rearrange ambiguous sentences, such as My brother, the teacher, and Mr. Green came to dinner. If the brother is also the teacher, this would be better as Mr Green and my brother, the teacher, came to dinner.

Top ↑

Consistency Consistency

Above all, be consistent. In addition to applying the above grammar rules consistently, it’s important to use terms and vocabulary consistently so as not to confuse the reader. This also makes it much easier for the localization team to translate the document.

In the following example, we use the terms data, ID, iteration, and query consistently.

Correct

To retrieve the data for all of the posts, don’t iterate through the array of IDs. This would result in a separate query being made for each ID on each iteration. It is much more efficient to make a single query that fetches all the data at once.

Incorrect

To retrieve the data for all of the posts, don’t iterate through the array of IDs. This would result in a separate SQL query being made for each post on each loop.  It is much more efficient to make one request to the database that fetches all the results at once.