Highlights Edit

This page provides a synopsis of the WordPress Style Guide.

For more information about guidelines or topics, follow the links.

General guidelines

• Follow a defined document structure throughout your documentation.
• Write in a conversational tone that is succinct, natural, and friendly towards the reader.
• Write documentation that is accessible to everyone.
• Write documentation for a global audience considering translation.
• Write documentation using inclusive language, word choice, and examples.
• Avoid making excessive claims about WordPress’ products and services. Don’t document or attempt to predict WordPress’ future features, products, or services.
• Write using your own words. Don’t copy content from external sources because it might infringe copyright.
• You can contribute to the WordPress Documentation Style Guide by opening a pull request on its GitHub repository.

Top ↑

Language and grammar

• Spell out and declare abbreviations whenever they are used for the first time. Avoid internet slang and jargon.
• Include definite and indefinite articles in your documentation.
• Follow standard American (US) English capitalization rules. In general, use sentence case capitalization.
• Put conditional clauses before instructions, not after.
• In most cases, using contractions is completely acceptable, but be watchful of some exceptions.
• In general, use indirect speech.
• In general, use second person.
• Capitalize proper nouns. Don’t use verbs as nouns or nouns as verbs.
• Pluralize a singular noun by adding -s at the end.
• To form a singular possessive, add an apostrophe-s.
• Don’t use three or more affixes in a single word.
• Use prepositions as needed, even at the ends of sentences.
• Ensure that a pronoun clearly refers to its antecedent.
• In general, write in present tense rather than future tense.
• Use precise verbs to write clear, succinct sentences.
• In general, use active voice rather than passive voice.
• Use common and simple technical terms that can be understood by the majority of readers.

Top ↑

Punctuation

• Use straight apostrophes.
• Use colons to initiate closely-related content that follows.
• Use commas to separate items in a series, and to separate certain kinds of clauses. Use serial commas.
• Use an em dash, to set off a break in the flow of a sentence. Use an en dash to indicate a range of numbers, the minus sign, or negative numbers.
• In general, avoid using ellipses.
• Only use exclamation points unless absolutely needed, except in code examples.
• Hyphenate words only when needed for clarity.
• Use parentheses sparingly.
• End all independent sentences with a period, and insert one space after the period.
• Use question marks sparingly.
• Use straight double quotation marks.
• Use semicolons to separate independent clauses.
• Avoid using slashes except in code examples, file paths, and URLs.

Top ↑

Formatting

• Use the day of week, month dd, year date format to express dates. Express time in the 12-hour format and always include AM and PM. Use Coordinated Universal Time (UTC) and always include the time zone for real times.
• Write unbiased examples without revealing personally identifiable information.
• Use all-lowercase filenames and separate words in filenames with hyphens.
• Avoid writing footnotes in documentation.
• Use sentence case for headings, and follow proper heading hierarchy.
• Use italics to emphasize or introduce a particular word or phrase in your content.
• Use numbered lists for sequences, bulleted lists for non-sequential items, and description lists for pairs of related pieces of data.
• Use SVG or PNG files and provide alt text for images.
• Use notices to warn, alert, notify, or provide useful information to readers.
• Spell out whole numbers from zero through nine. Follow proper formatting for numbers.
• Use a warning notice type to mark content as outdated.
• Use mock phone numbers instead of real ones in examples. Follow proper formatting for phone numbers.
• Use procedures to provide a sequence of numbered steps or instructions for achieving a particular task.
• Use tables to present lengthy and complex pieces of data that are related, in a well-structured format.
• Maintain consistent type and text formatting.
• Follow the trademark, licensing, and citation guidelines provided by the owners of the respective marks.
• Insert a nonbreaking space between the number and a unit of measurement.
• Italicize words used as words.

Top ↑

Linking

• Use cross-references to guide readers to related information.
• It’s OK to link to external sites for more information..
• Use heading anchors.
• Use root-relative URLs for image links.
• Write detailed and expressive link text that provides context.

Top ↑

Developer content

• Use code blocks, preformatted text, and code fences to write code examples.
• Insert code-related content in monospace code font.
• Follow WordPress coding standards.
• Follow proper command-line syntax and formatting.
• Enclose placeholders in a <var> element and use uppercase characters with underscore delimiters.
• Emphasize on the task to be accomplished, rather than how the user should interact with the UI element.
• Format UI element names in bold, and use appropriate nouns and verbs to describe how to interact with them.

Top ↑

Word list and usage dictionary

• Refer the word list for spellings and word usage guidelines for specific words.

Last updated: September 19, 2021