Highlight: An overview of some of the highlights of the Style Guide.
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.
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.
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.
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.
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.
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.