├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── docs ├── 1-introduction │ ├── README.md │ ├── changelog.md │ ├── highlights.md │ └── index.md ├── 2-general-guidelines │ ├── 1-document-structure.md │ ├── 2-style-voice-tone.md │ ├── 3-accessibility.md │ ├── 4-global-audience.md │ ├── 5-inclusivity.md │ ├── 6-facts-claims.md │ ├── 7-external-sources.md │ ├── 8-contributing-to-style-guide.md │ └── README.md ├── 3-language-grammar │ ├── README.md │ ├── abbreviations.md │ ├── articles.md │ ├── capitalization.md │ ├── clauses.md │ ├── contractions.md │ ├── direct-indirect-speech.md │ ├── grammatical-person.md │ ├── nouns.md │ ├── plurals.md │ ├── possessives.md │ ├── prefixes-suffixes.md │ ├── prepositions.md │ ├── pronouns.md │ ├── tense.md │ ├── verbs.md │ ├── voice.md │ └── word-choice.md ├── 4-punctuation │ ├── README.md │ ├── apostrophes.md │ ├── colons.md │ ├── commas.md │ ├── dashes.md │ ├── ellipses.md │ ├── exclamation-points.md │ ├── hyphens.md │ ├── parentheses.md │ ├── periods.md │ ├── question-marks.md │ ├── quotation-marks.md │ ├── semicolons.md │ └── slashes.md ├── 5-formatting │ ├── README.md │ ├── dates-times.md │ ├── examples.md │ ├── filenames.md │ ├── footnotes.md │ ├── headings.md │ ├── key-terms.md │ ├── lists.md │ ├── media.md │ ├── notices.md │ ├── numbers.md │ ├── obsolete-content.md │ ├── phone-numbers.md │ ├── procedures.md │ ├── tables.md │ ├── text.md │ ├── trademarks.md │ ├── units-of-measurement.md │ └── words-as-words.md ├── 6-linking │ ├── README.md │ ├── cross-references.md │ ├── external-links.md │ ├── heading-targets.md │ ├── image-links.md │ └── link-text.md ├── 7-developer-content │ ├── README.md │ ├── code-examples.md │ ├── code-in-text.md │ ├── coding-standards.md │ ├── command-line-syntax.md │ ├── placeholders.md │ └── ui-elements.md └── 8-word-list │ ├── README.md │ ├── a.md │ ├── b.md │ ├── c.md │ ├── d.md │ ├── e.md │ ├── f.md │ ├── g.md │ ├── h.md │ ├── i.md │ ├── j.md │ ├── k.md │ ├── l.md │ ├── m.md │ ├── n.md │ ├── numbers.md │ ├── o.md │ ├── p.md │ ├── q.md │ ├── r.md │ ├── s.md │ ├── symbols.md │ ├── t.md │ ├── u.md │ ├── v.md │ ├── w.md │ ├── x.md │ ├── y.md │ └── z.md └── manifest.json /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing guidelines 2 | 3 | See [Contributing to the Style Guide](https://github.com/WordPress/WordPress-Documentation-Style-Guide/blob/main/docs/2-general-guidelines/8-contributing-to-style-guide.md) for more information. 4 | 5 | Adhere to the [Code of conduct](https://make.wordpress.org/handbook/community-code-of-conduct/) and [WordPress Etiquette](https://wordpress.org/about/etiquette/). 6 | -------------------------------------------------------------------------------- /docs/1-introduction/README.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/WordPress/WordPress-Documentation-Style-Guide/a7ed44faf5bac5b9af22bbccf4579c0f2539de0d/docs/1-introduction/README.md -------------------------------------------------------------------------------- /docs/1-introduction/changelog.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | Update the changelog with an outline of significant changes to pages and components when they are added in the Style Guide. 4 | 5 | ## What's new 6 | 7 | This section shows recent updates and changes to the WordPress Style Guide. 8 | 9 | | **Date** | **Article** | **Description** | 10 | |----------|-------------|-----------------| 11 | | **September 11, 2021** | [Word list and usage dictionary](https://make.wordpress.org/docs/style-guide/word-list/) | Completed new *Word list and usage dictionary* section. | 12 | 13 | 14 | ## Release history 15 | 16 | | **Date** | **Description** | 17 | |----------|-----------------| 18 | | **March 15, 2021** | First Edition completed as part of [Google Season of Docs 2020](https://developers.google.com/season-of-docs/docs/2020/participants/project-wordpress-tacitonic) by Atharva Dhekne ([@tacitonic](https://github.com/tacitonic)). | 19 | | **March 15, 2021** | Initial public release. | 20 | -------------------------------------------------------------------------------- /docs/1-introduction/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | The WordPress Documentation Style Guide provides a set of rules and standards for writing developer and end-user documentation for any project related to WordPress. 4 | The primary objective of the WordPress Documentation Style Guide is to help authors write clear and accurate information while facilitating consistency across all documentation. The aim of this Style Guide is to accommodate the global WordPress community having varied skills and abilities. 5 | 6 | ## Highlights 7 | 8 | For an overview of the WordPress Documentation Style Guide, see [Highlights](https://make.wordpress.org/docs/style-guide/welcome/highlights/). 9 | 10 | ## Editorial resources 11 | 12 | Use these editorial resources for writing WordPress documentation. 13 | 14 | ### Reference hierarchy 15 | 16 | 1. **Project-specific style:** Follow style guidelines specific to your project or product with first preference, such as necessary exceptions to this guide or terms that are relevant only to your product. 17 | 18 | 2. **This style guide:** If certain guidelines are not there in your project-specific style guide, or there are no project-specific guidelines altogether, then use this style guide. 19 | 20 | 3. **External references:** If the preceding references don't provide explicit guidance, the refer the following external references: 21 | - [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html) 22 | - [The American Heritage Dictionary](https://ahdictionary.com/) 23 | - [Merriam-Webster](https://www.merriam-webster.com/) 24 | 25 | ### Additional editorial resources 26 | 27 | Following are some additional technical style guides: 28 | 29 | - [Google Developer Documentation Style Guide](https://developers.google.com/style) 30 | - [Microsoft Writing Style Guide](https://docs.microsoft.com/style-guide/welcome/) 31 | - [Apple Style Guide](https://help.apple.com/applestyleguide/) 32 | - [Red Hat technical documentation style guide](https://stylepedia.net/) 33 | - [Mozilla Writing style guide](https://developer.mozilla.org/docs/MDN/Guidelines/Writing_style_guide) 34 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/1-document-structure.md: -------------------------------------------------------------------------------- 1 | # Document structure 2 | 3 | [info] **Highlight:** Follow a defined document structure throughout your documentation. [/info] 4 | 5 | - Don't write walls of text in your documentation. Follow a defined structure throughout your documentation. 6 | - Break up long pages of text into paragraphs, lists, and illustrations. Use proper heading hierarchy. 7 | - Maintain a uniform structure for your document. Emphasize important points both stylistically and visually. 8 | - Use concise and simple sentence structures. Ensure that your tone is succinct, natural, and friendly towards the reader. 9 | 10 | For more information, see [Accessibility](https://make.wordpress.org/docs/style-guide/general-guidelines/accessibility/). 11 | 12 | ## Text formatting 13 | 14 | - Use consistent typographic formatting and font sizes for your documentation. 15 | - Use bold formatting for word emphasis and UI elements. Additionally, use italics formatting for names, terminology, etc. 16 | - For more information, see [Accessibility](https://make.wordpress.org/docs/style-guide/general-guidelines/accessibility/) and the [Formatting](https://make.wordpress.org/docs/style-guide/formatting/) section. 17 | 18 | ## Encoding 19 | 20 | - Ensure that proper character encoding is used. The UTF-8 character encoding is used universally, and is the preferred form of encoding. 21 | - Unicode encoding is preferred because of its single character encoding, by which you can handle any specific character that is needed. Using Unicode throughout your system also removes the need to track and convert between various character encodings. 22 | - Both developers and writers should use UTF-8 character encoding to ensure uniformity and eliminate inaccuracies in their content. 23 | - For more information about character encoding, see [W3C - Character encodings for beginners](https://www.w3.org/International/questions/qa-what-is-encoding). 24 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/2-style-voice-tone.md: -------------------------------------------------------------------------------- 1 | # Style, voice, and tone 2 | 3 | [info] **Highlight:** Write in a conversational tone that is succinct, natural, and friendly towards the reader. [/info] 4 | 5 | Always write your documents in simple, easy-to-understand sentences. *Voice* and *tone* refer to the mood or attitude of a specific work of writing. Ensure that your voice and tone is succinct, natural, and friendly towards the reader. Avoid a tone that is commanding or too pushy. Try to keep the document contents straightforward and effortless to understand. 6 | 7 | Don't try to be overly colloquial. On the other hand, don't overdo a professional tone; a formal or robotic tone is unfit as well. Try to achieve a balance between colloquial and formal language, that is suitable for providing knowledge and information. The document should persuade readers, rather than overwhelm them with verbiage. 8 | 9 | Even if a conversational tone helps, don't overplay the humor part. Keep the emphasis on the reader; the reader should not feel out of place. WordPress is a global project, with the majority of users being non-native English speakers. Hence, take into consideration that your document may be translated into other languages. Ultimately, educating and providing information to the reader is of the utmost priority. 10 | 11 | ## Try to avoid these things 12 | 13 | - Colloquial or idiomatic expressions. 14 | - Unnecessary metaphors or humor. 15 | - Cultural and regional references. 16 | - Technical jargon or slang. 17 | - Shortcuts, symbols, and abbreviations that could easily be spelled out. 18 | - Being overly pretentious or conspicuous. 19 | - Dictating or ordering procedures in a condescending tone. For example, *You must click __Publish__* or *You need to click __Publish__*. 20 | - Being overly polite. For example, *Please click __Publish__*. 21 | - Using exclamation points unless absolutely needed. 22 | - Capitalizing words where it is unnecessary. 23 | - Excess use of the same phrases and pronouns. 24 | - Ableist language or figures of speech. 25 | - Long, complicated, and disconnected sentences. 26 | - Content that would insult any group or individual. 27 | - Assumptions on the reader's fundamental understandings. 28 | - Using unorthodox conventions. 29 | - Heavily biased and disparaging information. 30 | 31 | Not complying to these guidelines may result in increased document perplexity and could impede the reader's understanding. 32 | 33 | ## Things that are encouraged 34 | 35 | - If you are finding it difficult to achieve a suitable tone and structure, try seeking input from your counterparts. 36 | - Proof-reading the document for the tone and structure. 37 | - Overall simplicity of the document. 38 | - Using transition words such as *moreover, although, hence,* and *therefore*. 39 | - Using [active voice](https://make.wordpress.org/docs/style-guide/language-grammar/voice/) whenever possible. 40 | - Using [contractions](https://make.wordpress.org/docs/style-guide/language-grammar/contractions/) such as *they've* and *don't*. 41 | - Brief and concise sentences. 42 | - Using [second person](https://make.wordpress.org/docs/style-guide/language-grammar/grammatical-person/#second-person) by keeping emphasis on the reader such as *you*. 43 | - Using conditional phrases. 44 | - Defining technical terms, jargon, and [abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/). 45 | - Referring proven [research and facts](https://make.wordpress.org/docs/style-guide/general-guidelines/facts-claims/). 46 | 47 | ## Tone for specific documentation types 48 | 49 | ### User documentation 50 | 51 | Users search through documentation for an answer to a question. Maintain a friendly, informal tone, but focus on being clear and concise in a knowledgeable manner. Get to the point promptly. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic. 52 | 53 | Write user documentation considering that many users are not native English speakers. Avoid long narrative paragraphs; keep paragraphs short and focused, with consistent vocabulary and phrasing that is easy to understand for readers. 54 | 55 | **Examples** 56 | [warning] **Not recommended:** If you peek over at the left side, you’ll see a menu called main navigation, which is the main menu. This menu is a list of functions you as the administrator can do from the administration screen. [/warning] 57 | [tip] **Recommended:** On the left side of the screen is the **Main navigation menu** listing the administrative functions you can perform. [/tip] 58 | [warning] **Not recommended:** When you visit a website, you probably want the website to remember some information about you so you don’t have to give it the information again. Websites can send your browser this kind of information so they remember you later. This information is called a cookie. I know what you’re thinking, a cookie is something you eat, right? Well, a computer cookie is different. It’s a tiny bit of data used by the website so that when you visit the website again, it gleans things from the cookie like what language you speak. [/warning] 59 | [tip] **Recommended:** A cookie is a small piece of data used to remember information about you. When you visit a website, it sends a cookie to your browser, and your browser stores the cookie in a small file. The next time you visit the website, it uses that cookie to get information such as your preferred language. [/tip] 60 | 61 | ### Developer documentation 62 | 63 | In most cases, developers are often searching through documentation for an answer to a specific technical question. Maintain a direct and precise tone while writing developer documentation. Use the same tone you would for user documentation, but you can assume a higher level of technical knowledge in your readers. In tutorials, it’s helpful to specify what technical knowledge is being assumed. 64 | 65 | For a code reference, be as direct as possible. A conversational tone is less appropriate here. 66 | 67 | **Examples** 68 | [warning] **Not recommended:** Sometimes you need to get a setting. This is easy if you use the `get_option()` function and pass in two parameters (a parameter is a value passed to a function). One parameter is the name and the other parameter is a default value. [/warning] 69 | [tip] **Recommended:** To retrieve an option, use the `get_option()` function. It accepts two parameters: the option name and a default value to return if the option does not exist. [/tip] 70 | [warning] **Not recommended:** Next, let’s talk about the `each` method. This method calls a function for each element and returns an array. [/warning] 71 | [tip] **Recommended:** The `each` method calls the provided function once for each element in the array. It returns the original array. [/tip] 72 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/3-accessibility.md: -------------------------------------------------------------------------------- 1 | # Accessibility 2 | 3 | [info] **Highlight:** Write documentation that is accessible to everyone. [/info] 4 | 5 | The WordPress community and the open source WordPress project is committed to being as inclusive and accessible as possible. This means ensuring users, regardless of device or ability, to be able to publish content and maintain a website or application built with WordPress. 6 | 7 | ## General guidelines 8 | 9 | - Emphasize the reader rather than underlining their inconveniences. 10 | - Don't refer a person with a disability as a disabled person (such as referring a *visually impaired person* as *blind* or *handicapped*). 11 | - Use approved terminology for people with specific disabilities; such as *Person with limited mobility* (rather than a person who is *crippled*). For more information, see [Writing inclusive documentation](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/). 12 | - Maintain a uniform structure for your document. Emphasize important points both stylistically and visually. 13 | - Use a screen reader to test your documentation. To test a screen reader, see [List of screen readers](https://wikipedia.org/wiki/List_of_screen_readers). 14 | - Consider multi-platform accessibility for all types of devices and operating systems. 15 | - Document all types of input devices such as voice and gesture based devices, controllers, mice, and keyboards. Avoid conventional verbs like *click*, *type*, and *touch/swipe* for interaction. Use inclusive verbs like *input*, *select*, etc. 16 | - Don't use ableist language. Be inclusive and unbiased while writing about accessibility and disability. 17 | - Take a pragmatic approach to HTML semantics. Don’t add semantics purely for the sake of semantics; but if there is an HTML structure that clearly matches the content, use that element. For example, if you have a group of links, it should most likely use a list element. 18 | - Use simple tables and tabular formats. Avoid span tags (such as `rowspan` and `colspan`). Tables prove to be difficult for screen readers. 19 | 20 | ## Text accessibility 21 | 22 | - Use concise and simple sentences. 23 | - Avoid camel case and all caps text; follow [capitalization](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/) guidelines. 24 | - Don't format fonts unnecessarily. For more information, see [Text formatting](https://make.wordpress.org/docs/style-guide/formatting/text/). 25 | - Use proper heading hierarchy. The H1 is the main heading representing the page title on every page or post (article). For subsections, use a correct HTML, Markdown, or relevant heading structure — including the use of heading elements for page subsections. Heading markup should not be used for presentational purposes. 26 | - Use H2 through H6 to give internal structure to the page. 27 | - Don’t skip heading levels. 28 | - Don’t add extra functionality inside a heading, like links or buttons. 29 | - Don't use colored or shaded backgrounds, images, or watermarks behind text. Low contrast hinders screen readers. 30 | - Avoid a screen full of continued text; rather break up your content in paragraphs and make use of headings, lists, bullet points, etc. 31 | - Define and spell out symbols, abbreviations or acronyms. 32 | - Don't limit the reader to forcefully open links in a new tab. When a link opens in a new tab, the user may lose the ability to go back in the browser. If the links do open in a new tab, indicate it using text or an icon. 33 | 34 | For more information, see [Text formatting](https://make.wordpress.org/docs/style-guide/formatting/text/). 35 | 36 | ## Media accessibility 37 | 38 | - Provide clear alternative descriptions for images. 39 | - Anything that the reader needs to know or do, must be in text as well. 40 | - Include `alt` and `figure` attributes/tags for images and illustrations. 41 | - Limit the alt text to 50 characters. 42 | - Use actual text rather than images of text. 43 | - Provide transcripts, closed-captions and descriptions for audio and video content. 44 | - Avoid auto-playing media. Provide controls to start, stop, and pause media. 45 | - Don't use flickering or flashing elements. Using them can cause seizures and/or motion sickness. 46 | 47 | For more information, see [Media](https://make.wordpress.org/docs/style-guide/formatting/media/). 48 | 49 | ## UI accessibility 50 | 51 | - Don't use direction-based guidelines solely, for navigating user interfaces (for example, '*Click the __Publish__ button on the right sidebar*'; rather than '*Go to the top and click the button.*'). 52 | - Clearly state error descriptions and ways to fix them. 53 | - Ensure that correct terminology is used for UI elements. Additional information about UI Elements. 54 | - Identify and inspect the regions of a page for their `aria-label`. Refer these UI elements by their terminology or by their `aria-label`. For more information, see [aria-label](https://www.w3.org/TR/WCAG20-TECHS/ARIA14.html). 55 | 56 | For more information, see [UI elements and interaction](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/). 57 | 58 | ## Document rendering 59 | 60 | - Consider that your document will be used on a multitude of devices. 61 | - Use proper color combinations and contrast ratios, with a [minimum ratio of 4.5:1](https://webaim.org/resources/contrastchecker/). Certain colors and patterns may cause problems for some people. 62 | - Don't rely on color solely to convey documentation. 63 | - Similarly, ensure that the document conveys all the information you intended when you view it in the following contexts: 64 | - Without sound 65 | - Using only sound 66 | - Without color 67 | - Using a keyboard 68 | - With screen magnification 69 | - Without punctuation 70 | 71 | ## Additional resources 72 | 73 | - [WordPress Accessibility About page](https://wordpress.org/about/accessibility/) 74 | - [WordPress Accessibility Team Homepage](https://make.wordpress.org/accessibility/) 75 | - [WordPress Accessibility Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/) 76 | - [WordPress Accessibility-ready themes](https://wordpress.org/themes/tags/accessibility-ready/) 77 | - [WordPress Accessibility Handbook](https://make.wordpress.org/accessibility/handbook/) 78 | - [Development Tools for creating accessible resources](https://make.wordpress.org/accessibility/handbook/which-tools-can-i-use/useful-tools/) 79 | - [WordPress Core issues with "accessibility" focus](https://core.trac.wordpress.org/focus/accessibility) 80 | - [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) 81 | - [Authoring Tool Accessibility Guidelines (ATAG) 2.0](https://www.w3.org/TR/ATAG20/) 82 | - [Web Content Accessibility Guidelines (WCAG) 2.0](https://www.w3.org/WAI/WCAG20/glance/) 83 | - [Using ARIA](https://www.w3.org/TR/using-aria/) 84 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/4-global-audience.md: -------------------------------------------------------------------------------- 1 | # Writing documentation for an international audience 2 | 3 | [info] **Highlight:** Write documentation for a global audience considering translation. [/info] 4 | 5 | WordPress is a global project, with its developer community and users spanning the globe. Both developers and users speak a variety of languages. Approaching documentation from a global perspective helps the understanding of readers around the globe; while also increasing its reach. 6 | 7 | Both developer and end-user WordPress documentation is written in US English. Just about [half of WordPress installs](https://wordpress.org/about/stats/) are in non-English locales. It is presumable that your documentation would be read by developers and users whose primary language is not English. Hence, writing documentation considering internationalization, localization, and translation is essential. 8 | 9 | ## What is internationalization, localization, and translation? 10 | 11 | Internationalization and localization (commonly abbreviated as *i18n* and *l10n* respectively) are terms used to describe the effort to make WordPress (and other such projects) available in languages other than the source, or original, language for people from different locales, who have different dialects and local preferences. 12 | 13 | The process of localizing software has two steps. The first step is when developers provide a mechanism and method for the eventual translation of the product and its interface to suit local preferences and languages for users worldwide. Its process includes designing the product and documentation such that localization requires minimum effort. This process is called internationalization (*i18n*). WordPress developers have done this already, so in theory, WordPress can be used in any language. 14 | 15 | The second step is the actual localization (*l10n*). It is the process by which a product or service is translated and adapted to another language and culture along with its documentation. The framework prescribed by developers of the software is used for this purpose. Localization is done by people who are familiar with the local language and culture. For example, the *l10n* process involves adapting to the laws, currency and political requirements of a specific locale (market). WordPress has already been localized into many languages (see WordPress' [list of teams](https://make.wordpress.org/polyglots/teams/) for more information). 16 | 17 | Translation is simply changing the language of the content to another language. Translation can be done by both editors from the community as well as machine-aided translation. 18 | 19 | ## General guidelines 20 | 21 | - If you write for international audiences, research, read, and learn more about them. 22 | - Don't be specific in terms of culture and religion in your documentation. 23 | - Use diverse examples that would cater to an international audience. These include diverse and inclusive names, email addresses, locations, and professions in examples. 24 | - Avoid colloquialisms, popular culture references, slang, and idioms in your documentation. Phrases like *you got it*, *that's sick!*, *cool* are hard to translate and perceive by global audiences. 25 | - Avoid culturally-specific humor and references to cultural practices, traditions, holidays, seasons, etc. 26 | - Express data using the standard international conventions. Measurement units, character encoding, currencies, text layouts, date and time formats, phone numbers etc. are different all over the world. Don't assume that everyone is familiar with US standards. 27 | 28 | ## Language guidelines 29 | 30 | - Write concise and succinct sentences, while using simple verbs and vocabulary. Longer sentences are difficult to translate and require higher effort. 31 | - If the sentence consists of more than a few commas, it usually indicates and complex sentence. Review the sentence and consider breaking it down to multiple sentences. Also, replace complex sentences and paragraphs with illustrations, tables, and lists. 32 | - Use active voice, present tense, and second person. 33 | - Avoid long chains of modifying words. Keep adverbs and adjectives close to their modifying words. Be mindful of placement of words like *only*. 34 | - Make abundant use of articles such as *a*, *an*, *the* and helper words such as *if*, *then*, etc. 35 | - Avoid shortcuts, symbols, and abbreviations that could easily be spelled out. 36 | - Ensure overall consistency in language - particularly names, terminology, punctuation and capitalization. 37 | - Use consistent text and media formatting. See additional information on [Text Formatting](). 38 | - Deviate from conventional standards only when there's a genuinely compelling purpose in implementing an unconventional style. 39 | 40 | ## Additional resources 41 | 42 | - [WordPress Polyglots Homepage](https://make.wordpress.org/polyglots/) 43 | - [WordPress Polyglots Handbook](https://make.wordpress.org/polyglots/handbook/) 44 | - [Translating WordPress Homepage](http://translate.wordpress.org/) 45 | - [Getting involved with WordPress translation](https://make.wordpress.org/polyglots/handbook/about/get-involved/first-steps/) 46 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/5-inclusivity.md: -------------------------------------------------------------------------------- 1 | # Writing inclusive documentation 2 | 3 | [info] **Highlight:** Write documentation using inclusive language, word choice, and examples. [/info] 4 | 5 | The WordPress community is welcoming and inclusive. Write WordPress documentation considering inclusivity of people of all demographics. 6 | 7 | ## Unbiased documentation 8 | 9 | Write documentation that is unbiased towards the reader and any kind of person in general. While documenting particularly demanding/sensitive topics, take the time to educate yourself thoroughly. Ensure that your document doesn't have content that may hurt or offend someone unintentionally. 10 | 11 | While writing unbiased documentation: 12 | - Be inclusive of gender identity, race, culture, ability, age, sexual orientation, and socioeconomic class. Include a wide variety of professions, educational settings, locales, and economic settings in examples. 13 | - Avoid politicized content. In case political content is to be included, remain neutral. 14 | - Follow [accessibility](https://make.wordpress.org/docs/style-guide/general-guidelines/accessibility/) guidelines. 15 | - Avoid content that would insult or cause harm to people. 16 | - Don't make any generalizations about people, countries, and cultures, not even positive or neutral generalizations. 17 | - Don't write prejudiced and discriminatory content against minority communities. 18 | - Avoid terms related to historical events. 19 | 20 | ### Replacing established terms 21 | 22 | Various words that are deemed to be non-inclusive are often used in documentation. If replacing those terms causes confusion for readers, you can refer to the non-inclusive term in parentheses in the first use, and subsequently use the inclusive term throughout the rest of the document. 23 | 24 | **Examples** 25 | [tip] **Recommended:** If `disallowed_keys` (sometimes called as `blacklist_keys`) exists in the database, the stored value will be returned. [/tip] 26 | [tip] **Recommended:** If `disallowed_keys` (previously known as `blacklist_keys`) exists in the database, the stored value will be returned. [/tip] 27 | [tip] **Recommended:** The comment blocklist (sometimes called a *blacklist*) shows blocked and spam comments. Comments that are not on the blocklist are published. [/tip] 28 | 29 | | **Recommended** | **Not Recommended** | 30 | |-----------------|---------------------| 31 | | deny list, blocklist, disallowed, unapproved | blacklist | 32 | | allowlist, allowed, approved | whitelist | 33 | | main | master | 34 | | primary/subordinate | master/slave | 35 | | site admin, website author, web developer | webmaster | 36 | | built-in, core | native | 37 | 38 | ## Avoid ableist and profane language 39 | 40 | Be thoughtful of word choice - particularly slang and ableist language. Don't use slang, violent and derogatory language such as *dumbass* and *bitch*. 41 | 42 | **Examples** 43 | [warning] **Not recommended:** Gutenberg is damn useful stuff. [/warning] 44 | [tip] **Recommended:** Gutenberg is a versatile editor. [/tip] 45 | [warning] **Not recommended:** Only morons use this API. [/warning] 46 | [tip] **Recommended:** Using this API is not advised. [/tip] 47 | 48 | ## Writing about genders 49 | 50 | Use gender-neutral language, including pronouns. When writing about a real individual, use their preferred pronouns. Avoid gendered language such as *manpower*, *man-hours*, *chairman*, etc. For more information, see [Pronouns and genders](https://make.wordpress.org/docs/style-guide/language-grammar/pronouns/#pronouns-and-genders) and [they, their, them](https://make.wordpress.org/docs/style-guide/word-list/t/#they-their-them). 51 | 52 | **Examples** 53 | 54 | | **Recommended** | **Not Recommended** | 55 | |----------------------|---------------------| 56 | | human-power, staff, personnel, workforce | manpower | 57 | | humankind, humanity, people | man, mankind | 58 | | operates, controls, utilizes | mans | 59 | | manufactured | manmade | 60 | | chairperson | chairman | 61 | | everyone, folks, people | guys, gals, girls, boys | 62 | 63 | Don't use *he, him, his, she, her, or hers* while referencing people. To write around pronouns, you can: 64 | - Rewrite using the second person (*you*). 65 | - Rewrite the sentence to have a plural noun and pronoun. 66 | - Use the words *person* or *individual*. 67 | - Use articles *the, an,* or *a* instead of a pronoun. 68 | - Use a plural pronoun such as *they, their*, or *them*, even if it references a single individual. 69 | 70 | When writing about a person, use the pronouns that the person prefers. Only use gendered pronouns such as *he, him, his, she, her, or hers,* or other pronouns if a particular individual prefers to be identified with them. It's acceptable to use gendered pronouns in direct quotations of people who prefer being identified with those pronouns. 71 | 72 | ## Using diverse examples 73 | 74 | Represent diverse perspectives and scenarios in text and media. Make use of inclusive and a diverse range of names, ages, gender identities, locations, professions, and cultures while depicting people. 75 | - Avoid making generalizations about people, religions, cultures, regions, and countries. 76 | - Avoid unintentional racial and cultural bias while writing examples. 77 | 78 | ## Accessibility and disability 79 | 80 | - Research the terminology that the people with disability want to be identified with. 81 | - Don't refer to people without disabilities as *normal, fit or healthy*; terms that would demean people with disabilities. This includes terms that are judgmental and victimize people with disabilities as *abnormal* or *sick*. 82 | 83 | ### Accessibility terminology 84 | 85 | | **Recommended** | **Not Recommended** | 86 | |--------------------------|---------------------| 87 | | person with disability | the disabled, handicapped, differently abled, challenged, abnormal | 88 | | person without disability | normal person, healthy person, able-bodied | 89 | | has [disability] | victim of, suffering from, affected by, stricken with | 90 | | unable to speak, uses synthetic speech | dumb, mute | 91 | | deaf, low-hearing | hearing-impaired | 92 | | blind, low-vision | vision-impaired, visually-challenged | 93 | | cognitive or developmental disabilities | mentally-challenged, slow-learner | 94 | | person with limited mobility, person with a physical disability | crippled, handicapped | 95 | 96 | For more information, see [Accessibility](https://make.wordpress.org/docs/style-guide/general-guidelines/accessibility/). 97 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/6-facts-claims.md: -------------------------------------------------------------------------------- 1 | # Facts and claims 2 | 3 | [info] **Highlight:** Avoid making excessive claims about WordPress' products and services. Don't document or attempt to predict WordPress' future features, products, or services. [/info] 4 | 5 | ## Avoid excessive claims 6 | 7 | Avoid making excessive claims about WordPress' products and services. Abide with proven facts as frequently as possible. If you are unsure about some details, research about it. Reach out to the respective people via the communication channels for further clarifications. 8 | 9 | ## Avoid ambiguities 10 | 11 | If a particular fact is not verified or proven, don't go into ambiguities. Substantiate facts without exception, and then include them to your document. 12 | 13 | ## Documenting future features 14 | 15 | Don't document or attempt to predict WordPress' future features, products, or services unless explicitly specified. 16 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/7-external-sources.md: -------------------------------------------------------------------------------- 1 | # External sources 2 | 3 | [info] **Highlight:** Write using your own words. Don't copy content from external sources because it might infringe copyright. [/info] 4 | 5 | Don't copy content from external sources because it might infringe copyright. Instead, paraphrase and link to their content. The types of content that may be copyrighted, include and are not limited to: 6 | - Text 7 | - Media (Images, audio, video) 8 | - Code 9 | - Logos and trademarks 10 | 11 | **Examples** 12 | [warning] **Not recommended:** Extensible Markup Language-Remote Procedure Call (XML-RPC): "XML-RPC is a remote procedure call (RPC) protocol which uses XML to encode its calls and HTTP as a transport mechanism" (https://wikipedia.org/wiki/XML-RPC). [/warning] 13 | [tip] **Recommended:** [Extensible Markup Language-Remote Procedure Call (XML-RPC)](https://wikipedia.org/wiki/XML-RPC) is a remote procedure call (RPC) protocol that allows a user or developer to send a request, formatted in XML, to an external application. [/tip] 14 | 15 | ## Avoiding third-party content 16 | 17 | Avoid copying third-party content, unless you're sure that you or your organization own the assets, or the rights to use those assets. However, you can reference external third-party content by linking to it. For additional information about linking to other sites, see [External links](https://make.wordpress.org/docs/style-guide/linking/external-links/). 18 | 19 | Avoid copying content from these sources: 20 | - Third-party sources: Avoid copying from third-party sources which include but are not limited to documentation, websites, books, images, videos, papers, blogs, podcasts, and other works. 21 | - Reference sources: Avoid copying from dictionaries, encyclopedias, and Wikipedia. 22 | - Open source product documentation: Open source software (OSS) has different license options, which can range from no reuse without attribution, to complete freedom to use the material; each license is different and governs different aspects of a project. It's not safe to assume that you can reuse this content freely. When in doubt, don't use their content. 23 | - GitHub: Users have the ability to license their repository and content to change and distribute open source software. Each license is different and governs different aspects of a project. It's not safe to assume that you can reuse this content freely. When in doubt, don't use their content. 24 | 25 | ## Reusing content 26 | 27 | You can reuse content if you or your organization are the source of that content, or have the rights to it. 28 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/8-contributing-to-style-guide.md: -------------------------------------------------------------------------------- 1 | # Contributing to the Style Guide 2 | 3 | [info] **Highlight:** You can contribute to the WordPress Documentation Style Guide by opening a pull request on its GitHub repository. [/info] 4 | 5 | You can contribute to the Style Guide by forking the [GitHub repository for the WordPress Documentation Style Guide](https://github.com/WordPress/WordPress-Documentation-Style-Guide) and opening a pull request on your forked repository. 6 | 7 | If your PR is merged, update the [Changelog](https://make.wordpress.org/docs/style-guide/welcome/changelog/) with the relevant changes. 8 | 9 | You can also send a message in the [#docs channel](https://wordpress.slack.com/archives/docs/) on the official [WordPress Slack](https://make.wordpress.org/chat/). 10 | -------------------------------------------------------------------------------- /docs/2-general-guidelines/README.md: -------------------------------------------------------------------------------- 1 | # General guidelines 2 | 3 | This section provides general guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/3-language-grammar/README.md: -------------------------------------------------------------------------------- 1 | # Language and grammar 2 | 3 | This section provides language and grammar guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/3-language-grammar/abbreviations.md: -------------------------------------------------------------------------------- 1 | # Abbreviations 2 | 3 | [info] **Highlight:** Spell out and declare abbreviations whenever they are used for the first time. Avoid internet slang and jargon. [/info] 4 | 5 | Abbreviations include acronyms, initialisms, contractions, and shortened phrases and words. 6 | 7 | - An acronym is formed from the initial letters of words from a particular phrase. Acronyms are pronounced as words themselves. 8 | - *Laser - Light amplification by stimulated emission of radiation* 9 | - *Radar - Radio detection and ranging* 10 | - *LAN - Local Area Network* 11 | - *CRUD - Create, Read, Update, Delete* 12 | - An initialism is formed from the initial letters of words from a particular phrase, but each letter is pronounced separately. 13 | - *HTML - Hyper Text Markup Language* 14 | - *PST - Pacific Standard Time* 15 | - *USB - Universal Serial Bus* 16 | - *IMO - In My Opinion* 17 | - A contraction is a short form of a word or a combination of words that is often used instead of the full form in spoken English. 18 | - *I'm - I am* 19 | - *they've - they have* 20 | - *wanna - want to* 21 | - For more information, see [Contractions](https://make.wordpress.org/docs/style-guide/language-grammar/contractions/). 22 | - A shortened word or phrase which is part of the word or phrase, but condensed; sometimes with a period at the end. 23 | - *Dr. - Doctor* 24 | - *Rd. - Road* 25 | - *etc. - et cetera* 26 | - *min - minutes* 27 | - Sometimes the long and short versions of a word are used interchangeably. These words don't need a period at the end. 28 | - *max - Maximum* 29 | - *info - Information* 30 | - *app - Application* 31 | - *uni - University* 32 | 33 | Some words often have concurrent characteristics of acronyms, initialisms, or shortened words. Words like GUI, GIF could be either spoken as an acronym or an initialism; subject to preference of the speaker. 34 | 35 | ## Spelling out and declaring abbreviations 36 | 37 | Spell out and declare abbreviations whenever they are used for the first time in a document. Avoid using abbreviations in titles and headings, unless absolutely necessary. If using an abbreviation in a heading/title is mandatory, spell out the abbreviation in the succeeding body text. 38 | Upon successive mentions of the abbreviation in the document, you can use the abbreviation without spelling it out. 39 | 40 | Consider your audience while defining or spelling-out an abbreviation. Some abbreviations like PC, RAM, USB, PDF are more well-known than their spelled-out terms. A developer demographic would be familiar with HTML, whereas a beginner or a general reader may not. In which case, it is up to you to decide whether a particular abbreviation needs to be spelled out. If you're sure that your reader demographic is expected to understand the term, then you don't need to spell it out. 41 | 42 | Sometimes, readers may not understand that a Universal Serial Bus port might be a USB port. In these cases, not spelling out the word is preferred. 43 | 44 | ## Abbreviations to be avoided 45 | 46 | If an abbreviation appears only once in your document, just spell out the term. Don't introduce it in parentheses after the spelled-out version. Use the most common form of the word/phrase. If the full word or phrase is most commons and understandable, use that rather than its abbreviation. For example, write *approximately* instead of *approx*. 47 | 48 | Avoid internet slang abbreviations such as *tbh (to be honest)*, *fwiw (for what it's worth)*, *tl;dr (too long; didn't read)*. Rephrase the sentence in an objective approach. 49 | 50 | Use English terms over Latin abbreviations such as *et al.*, *eg.*, *viz.*; use *and others*, *for example*, *namely* instead of these. 51 | 52 | Don't add an *s* in abbreviations of measurements to indicate plurality. For example, 50 mi or 10 mm. 53 | 54 | ## Articles 55 | 56 | The article (*a* or *an*) that goes along with an abbreviation depends on whether the term is pronounced like an acronym or an initialism. For example, *an* API, *an* IDE, *a* URL, *a* CMS are the articles that go with these terms. 57 | 58 | ## Capitalization 59 | 60 | Lowercase all the words in the spelled-out form except for the proper nouns. Words like *as*, *of*, *the*, in abbreviations are rarely capitalized - sometimes not even included in the abbreviations. For example, *NASA - National Aeronautics and Space Administration* doesn't include *and* in its abbreviation. On the contrary, the *DOT - Department of Transportation* includes an *of* in its abbreviation while also capitalizing it. Therefore, confirm the abbreviation and its spelled-out form for the concerned terms. Refer the [Word list and usage dictionary](https://make.wordpress.org/docs/style-guide/word-list/) for more information. 61 | 62 | ## Periods 63 | 64 | Use periods at the end of shortened words. Don't use periods with acronyms and initialisms. Similarly, don't use periods with commons words that are abbreviations such as *app* or *demo*. Don't use a period with an abbreviation for the name of a country, US state, or the District of Columbia (DC). 65 | 66 | ## Plurals of abbreviations 67 | 68 | The plural of an abbreviation can be formed like any other regular term; if the abbreviation is for a singular noun, add a lowercase *s* to form its plural. If the abbreviation is for a plural noun, don't add an *s*. Examples include APIs, CMSs, IDEs. Also ensure that the possessive form of the word (an apostrophe *'* before the *s*) is not used. 69 | -------------------------------------------------------------------------------- /docs/3-language-grammar/articles.md: -------------------------------------------------------------------------------- 1 | # Articles (a, an, the) 2 | 3 | [info] **Highlight:** Include definite and indefinite articles in your documentation. [/info] 4 | 5 | Articles modify nouns. *The* is a definite article, and is used to define specific or particular nouns. 6 | *A* and *an* are indefinite articles, and are used to define non-specific or non-particular nouns. 7 | 8 | For example, 'I watched *the* video.' Here, *the* particular video is being watched. 9 | 'I watched *a* video.' Here, it may be any video that is being watched. 10 | 11 | Including articles in your writing is essential for overall simplicity of language and ease of understanding. 12 | 13 | **Examples of articles** 14 | 15 | - A document 16 | - An hour 17 | - A link 18 | - A project 19 | - An open source project 20 | - An issue 21 | - A new issue 22 | 23 | Using *a* or *an* depends on the pronunciation of the succeeding word. Basically, *a* is used before any consonant sound, and *an* is used before any vowel sound. 24 | 25 | The article (*a* or *an*) that goes along with an abbreviation depends on whether the term is pronounced like an acronym or an initialism. For example, *an* API, *an* IDE, *a* URL, *a* CMS are the articles that go with these terms. 26 | 27 | For more information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/). 28 | 29 | ## Additional resources 30 | 31 | - [The Purdue Online Writing Lab - Using Articles](https://owl.purdue.edu/owl/general_writing/grammar/using_articles.html) 32 | -------------------------------------------------------------------------------- /docs/3-language-grammar/capitalization.md: -------------------------------------------------------------------------------- 1 | # Capitalization 2 | 3 | [info] **Highlight:** Follow standard American (US) English capitalization rules. In general, use sentence case capitalization. [/info] 4 | 5 | WordPress follows American (US) English capitalization rules. In general, sentence-case capitalization is used. Sentence case capitalization means capitalizing the first word of a sentence or a phrase and the proper nouns. 6 | 7 | ## General do's and don'ts 8 | 9 | - Capitalize the first word of a sentence, phrase, heading, title, or any element. 10 | - Always capitalize proper nouns. Proper nouns include, names, places, brand names, organizations, companies, software, products, services, and whatever the organizations deem to be capitalized. Use lowercase for everything else. 11 | - If an official name, term, abbreviation, or code snippet begins with a lowercase, is all-uppercase, or a mix of both uppercase and lowercase, then don't alter it. 12 | - Rephrase sentences that start with a lowercase term to avoid the lowercase term in the beginning. 13 | - Don't capitalize words unnecessarily. If in doubt, don't capitalize the term. 14 | - Don't use all-uppercase for emphasizing text. Also, don't use all-lowercase as a design preference. In both instances, text is difficult to read and it becomes difficult to distinguish between sentences. 15 | - Avoid camel case, except while representing code or official terminology. 16 | - While referencing or quoting external sources, use the original capitalization. Don't alter the capitalization even if it is incorrect. 17 | 18 | ## Capitalization in titles and headings 19 | 20 | Use sentence-case capitalization in titles and headings. Capitalize the first word in the title or heading, sub-heading, any proper nouns, and official terms. If a title or heading includes a colon, capitalize the following word. 21 | 22 | Lowercase all other words and terms. Don't end the title or heading with a period. For example, *'Creating a block for the Gutenberg block editor'*. 23 | 24 | ### Capitalization in references to titles and headings 25 | 26 | When linking to a title, heading, or subheading as a reference from a document that follows this guide, use sentence-case capitalization even if the title or heading itself uses title case. That way, when the title or heading is eventually updated to sentence case, the reference will match. 27 | 28 | In references to titles, headings, or subheadings that don't follow this guide or external sources, retain the original capitalization. For additional information about formatting third-party links, see [Formatting cross-references](https://make.wordpress.org/docs/style-guide/linking/cross-references/#formatting-cross-references). 29 | 30 | For more information about internal and external references, see [Cross-references](https://make.wordpress.org/docs/style-guide/linking/cross-references/). 31 | 32 | ## Capitalization in indexes and glossaries 33 | 34 | Apart from proper nouns and official terminology, use lowercase for index and glossary terms. Use sentence case for glossary definitions. 35 | 36 | ## Capitalization in tables and lists 37 | 38 | Use sentence case for tables, lists and all their elements. 39 | 40 | ## Capitalization and colons 41 | 42 | Capitalize text after a colon if they are headings, titles, proper nouns, official terminology, and quotations. Use lowercase if the text following the colon is exclusive of this criteria. 43 | 44 | **Examples** 45 | 46 | - Directory structure: Home 47 | - Block Editor: Making a Block 48 | - Our founder: John D. 49 | 50 | ## Capitalization and hyphens 51 | 52 | Capitalize only the first element in a hyphenated word, unless a subsequent element is a proper noun or proper adjective. 53 | 54 | ## Capitalization and illustrations 55 | 56 | Capitalize terms using sentence case. Capitalize labels, captions, and other supplemental text in illustrations. 57 | 58 | ## Capitalization and slashes 59 | 60 | For words using a slash, capitalize the word after the slash if the word before it is capitalized. 61 | 62 | **Examples** 63 | 64 | - *Region/Location* 65 | - *Press the On/Off switch.* 66 | 67 | ## Title case capitalization 68 | 69 | Title case capitalization may be used at times, depending on the context. Title case capitalization is sometimes used in article, book, or blog titles, research paper titles, and titles of people (such as *Managing Director*). In most cases, sentence-case capitalization is used. 70 | The general rules for title case capitalization are: 71 | - Capitalize the first and last words. 72 | - Capitalize all words including nouns, verbs, adverbs, adjectives, and pronouns. 73 | - Don't capitalize articles (*a*, *an*, *the*) unless it's the first word. 74 | - Don't capitalize prepositions such as *of, to, on, in, for*, etc. as long as they are four or fewer lettered words. Don't capitalize *but, or, yet*, etc. unless it's the first or last word. 75 | 76 | ## Additional resources 77 | 78 | - [Purdue Online Writing Lab - Capitals](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) 79 | -------------------------------------------------------------------------------- /docs/3-language-grammar/clauses.md: -------------------------------------------------------------------------------- 1 | # Clauses 2 | 3 | [info] **Highlight:** Put conditional clauses before instructions, not after. [/info] 4 | 5 | Conditional sentences consist of a main clause and a conditional clause. The conditional clause, also known as the if-clause, begins with an *if* or *unless*. The conditional clause can come before or after the main clause. 6 | For example, 7 | - The console will show an error, if you use the old API. 8 | - If you use the old API, the console will show an error. 9 | 10 | In this particular example, the reader would have to read the entire sentence to interpret it. If the reader isn't using the *old API*, they can skip the instruction, if needed. Therefore, put conditional clauses before instructions (main clauses), rather than after them. 11 | 12 | **Examples** 13 | [warning] **Not recommended:** Click **Install** if you want to install the plugin. [/warning] 14 | [tip] **Recommended:** To install the plugin, click **Install**. [/tip] 15 | [warning] **Not recommended:** WordPress will need write access to the `.htaccess` file if you want to update it automatically. [/warning] 16 | [tip] **Recommended:** If you want WordPress to update the `.htaccess` file automatically, WordPress will need write access to the file. [/tip] 17 | [warning] **Not recommended:** See https://wordpress.org/about/accessibility/ for more information on accessibility.[/warning] 18 | [tip] **Recommended:** For more information on accessibility, see https://wordpress.org/about/accessibility/.[/tip] 19 | -------------------------------------------------------------------------------- /docs/3-language-grammar/contractions.md: -------------------------------------------------------------------------------- 1 | # Contractions 2 | 3 | [info] **Highlight:** In most cases, using contractions is completely acceptable, but be watchful of some exceptions. [/info] 4 | 5 | A contraction is a shortened form of a word, syllable, or a combination of words that is often used instead of the full form in spoken English. Generally, the letters omitted by contractions are indicated with an apostrophe ( *'* ). Contractions are commonly used in colloquial and informal settings. 6 | 7 | As WordPress documentation makes use of a colloquial tone, you can utilize contractions in your content. Although, be watchful of some exceptions. 8 | 9 | **Examples** 10 | 11 | - *I'm - I am*. 12 | - *they've - they have*. 13 | - *don't - do not*. 14 | 15 | ## Common contractions 16 | 17 | - Use common contractions such as *they've, that's, you're, it's*, in your documentation. 18 | - Be wary of common mistakes such as confusing *you're* with *your*, and *it's* with *its*. 19 | - Use negation contractions such as *don't, can't, shouldn't,* and *isn't*. 20 | - Avoid awkward and unconventional contractions such as *where're, mightn't, mayn't, 'twas'*, and slang contractions like *gotta, imma, wanna*. 21 | 22 | ## Noun and verb contractions 23 | 24 | Don't use contractions formed with nouns and verbs. Contractions formed with nouns and verbs are generally complex and uncommon words. 25 | 26 | **Examples** 27 | [warning] **Not recommended:** Gutenberg's using a new, refreshed UI. [/warning] 28 | [tip] **Recommended:** Gutenberg is using a new, refreshed UI. [/tip] 29 | [warning] **Not recommended:** These formats've proven to be highly beneficial. [/warning] 30 | [tip] **Recommended:** These formats have proven to be highly beneficial. [/tip] 31 | 32 | ## Double contractions 33 | 34 | Avoid using double contractions. Double contractions contain two contractions as opposed to one. 35 | 36 | **Examples** 37 | 38 | - *wouldn't've - would not have*. 39 | - *you'd've - you would have*. 40 | - *sha'n't - shall not (shall + n't)*. 41 | - *mightn't've - might not have*. 42 | - *'tisn't - it is not*. 43 | 44 | Double contractions, including slang and archaic, are difficult to understand. Avoid using these in documentation. 45 | 46 | ## Additional Resources 47 | 48 | - [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/) 49 | - [Wikipedia - List of English Contractions](https://wikipedia.org/wiki/Wikipedia:List_of_English_contractions) 50 | -------------------------------------------------------------------------------- /docs/3-language-grammar/direct-indirect-speech.md: -------------------------------------------------------------------------------- 1 | # Direct and indirect speech 2 | 3 | [info] **Highlight:** In general, use indirect speech. [/info] 4 | 5 | In documentation, sometimes you have to convey what someone has expressed from a previous conversation, to the reader. This can be done in two methods, direct speech or indirect speech. In general, use indirect speech so that readers don't have to distinguish between speakers and their quotes. 6 | 7 | ## Direct speech 8 | 9 | In direct speech, the speaker's words are directly quoted word-to-word without any change. The words that are spoken by the speaker are enclosed in quotation marks with a comma before the initial quotation marks to introduce the speaker. Use double quotation marks as per American (US) English guidelines. Punctuation such as a period, comma, question mark, exclamation mark should be inside quotation marks. 10 | 11 | **Examples** 12 | 13 | **Developer's expression:** This API is the newest version. 14 | **Direct speech:** The developer said, "This API is the newest version." 15 | **Direct speech:** "This API," the developer said, "is the newest version." 16 | 17 | Avoid using direct speech by breaking up information about who is speaking. This impedes the understanding of the reader. 18 | 19 | ## Indirect or reported speech 20 | 21 | In indirect or reported speech, the speaker's words are reported by paraphrasing or summarizing. Unlike direct speech, the words not quoted directly and there is no additional punctuation to be used. Verbs that better describe the person's action are used while paraphrasing in indirect speech, whereas while summarizing, standard verbs like *say, tell, talk, speak* are used. 22 | 23 | **Examples** 24 | 25 | **Developer's expression:** This API is the newest version. 26 | **Indirect speech (summarized):** The developer *said* that this API is the newest version. 27 | **Indirect speech (paraphrased):** The developer *asserted* that this API is the newest version. 28 | -------------------------------------------------------------------------------- /docs/3-language-grammar/grammatical-person.md: -------------------------------------------------------------------------------- 1 | # Grammatical person 2 | 3 | [info] **Highlight:** In general, use second person. [/info] 4 | 5 | Grammatical *person* is used to refer to different people in a statement, and describe the verbs and pronouns that refer them. 6 | 7 | Briefly, the first person refers to the person speaking (*I, we*), the second person refers to the person being spoken to (*you*), and the third person refers to another person or thing being spoken about (*he, she, it, they*). 8 | 9 | ## Second person 10 | 11 | In general, use second person in your documentation. Second person depicts a friendly tone, with a perfect focus on the reader. In addition to this, directly addressing the reader helps avoid passive voice; thereby preventing unwanted confusion. 12 | 13 | ## First person 14 | 15 | Use first person (*I, we*) only when absolutely needed. First person may be used in quotes, direct references, and personifications. First person plurals such as *we* and *our* may intimidate the reader in some cases. Try to avoid first person plurals, but be cautious if you're using them. 16 | 17 | **Examples** 18 | 19 | [warning] **Not recommended:** Add an embed block to our page. [/warning] 20 | [tip] **Recommended:** Add an embed block to your page. [/tip] 21 | [warning] **Not recommended:** We need to click **Add Block**. [/warning] 22 | [warning] **Not recommended:** You'll need to click **Add Block**. [/warning] 23 | [tip] **Recommended:** Click **Add Block**. [/tip] 24 | [warning] **Not recommended:** We at WordPress are committed to being as inclusive and accessible as possible. [/warning] 25 | [tip] **Recommended:** The WordPress community is committed to being as inclusive and accessible as possible. [/tip] 26 | [warning] **Not recommended:** For additional details, refer our website. [/warning] 27 | [tip] **Recommended:** For additional details, refer WordPress.org. [/tip] 28 | 29 | ## Additional resources 30 | 31 | - [Wikipedia - Grammatical Person](https://wikipedia.org/wiki/Grammatical_person) 32 | -------------------------------------------------------------------------------- /docs/3-language-grammar/nouns.md: -------------------------------------------------------------------------------- 1 | # Nouns 2 | 3 | [info] **Highlight:** Capitalize proper nouns. Don't use verbs as nouns or nouns as verbs. [/info] 4 | 5 | A noun is a word used to identify people, places, or things (common noun), or particular person, place, or thing (proper noun). 6 | 7 | ## Proper nouns 8 | 9 | Proper nouns are unique people, places, and things. Always capitalize proper nouns in sentences. 10 | Proper nouns include: 11 | - Names and titles of individuals. 12 | - Names of places. 13 | - Brand names, names of organizations and companies. 14 | - Software, product, application, and service names. 15 | - Names and titles of works such as books, articles, songs, etc. 16 | - Trademarks and standards. 17 | 18 | For more information about capitalizing words and proper nouns, see [Capitalization](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/). 19 | 20 | ## Common nouns 21 | 22 | If there is more than one thing, then it is a common noun. Don't capitalize common nouns unless they are at the beginning of a sentence, or if the sentence implements title case capitalization. For example, there are multiple websites, so *website* is a common noun. But, *WordPress* is a unique website out of all of them, therefore, it is a proper noun. 23 | 24 | Common nouns include most product categories, devices, features, and technology concepts such as *email, laptop, machine learning, website,* and *server*. 25 | 26 | ## Verbs as nouns 27 | 28 | Don't use verbs as nouns or nouns as verbs. 29 | 30 | **Examples** 31 | [warning] **Not recommended:** Get the download. [/warning] 32 | [tip] **Recommended:** Download the document. [/tip] 33 | [warning] **Not recommended:** Calculate the estimate. [/warning] 34 | [tip] **Recommended:** Calculate the estimation. [/tip] 35 | 36 | ## Additional resources 37 | 38 | - [Pronouns and collective nouns](https://make.wordpress.org/docs/style-guide/language-grammar/pronouns/#pronouns-and-collective-nouns) 39 | - [Plurals and nouns](https://make.wordpress.org/docs/style-guide/language-grammar/plurals/#plurals-and-nouns) 40 | -------------------------------------------------------------------------------- /docs/3-language-grammar/plurals.md: -------------------------------------------------------------------------------- 1 | # Plurals 2 | 3 | [info] **Highlight:** Pluralize a singular noun by adding *-s* at the end. [/info] 4 | 5 | ## Plurals and nouns 6 | 7 | If a singular noun ends without an *-s*, add an *s* at the end to get its plural form. If a singular noun ends with an *-s, -ss, -sh, -ch, -x, or -z*, add an *es* at the end to get its plural from. Additional information on plurals and their exceptions can be found [on Wikipedia](https://wikipedia.org/wiki/English_plurals). 8 | - computer - *computers* 9 | - page - *pages* 10 | - tax - *taxes* 11 | - bias - *biases* 12 | 13 | ## Plurals and numbers 14 | 15 | To pluralize a number, add an *-s* at the end. 16 | - The 2000s. 17 | - Type five 7s. 18 | 19 | Don't add an *s* in abbreviations of measurements to indicate plurality. For example, 50 mi or 10 mm; not 50 mis, 50 mi's, 10 mms, or 10 mm's. 20 | 21 | ## Plurals and abbreviations 22 | 23 | Don't use apostrophes to form plurals of abbreviations. The plural of an abbreviation can be formed like any other regular term; if the abbreviation is for a singular noun, add a lowercase *s* to form its plural. If the abbreviation is for a plural noun, don't add an *s*. Also ensure that the possessive form of the word (an apostrophe *'* before the *s*) is not used. 24 | - APIs 25 | - CMSs 26 | - IDEs 27 | 28 | For additional information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/). 29 | 30 | ## Plurals and symbols 31 | 32 | Avoid pluralizing symbols, signs, and individual letters by adding an apostrophe and an *s* at the end. 33 | 34 | **Examples** 35 | [warning] **Not recommended:** Invalid characters include x's, $'s, @'s, and #'s. [/warning] 36 | [tip] **Recommended:** Invalid characters include the letter *x* and the symbols $, @, and #. [/tip] 37 | 38 | ## Plurals in parentheses 39 | 40 | Don't put optional plurals in parentheses, rather use either the plural or singular form of the word. Determine a word form that is most appropriate for your documentation and stay consistent with its usage. If it is essential to indicate both, use *one or more*. 41 | Avoid adding *(s)* to indicate the plural form of a variable. Use the plural form of its unit instead. 42 | 43 | **Examples** 44 | [warning] **Not recommended:** To see your existing post(s), go to the Posts page. [/warning] 45 | [tip] **Recommended:** To see your existing posts, go to the Posts page. [/tip] 46 | [warning] **Not recommended:** You can categorize your post with tag(s). [/warning] 47 | [tip] **Recommended:** You can categorize your post with one or more tags. [/tip] 48 | [tip] **Recommended:** You can categorize your post with multiple tags. [/tip] 49 | [warning] **Not recommended:** Making changes to the code while running the server could cause error(s) in your database(s). [/warning] 50 | [tip] **Recommended:** Making changes to the code while running the server could cause errors in your databases. [/tip] 51 | [warning] **Not recommended:** The function will execute in *x* minute(s). [/warning] 52 | [tip] **Recommended:** The function will execute in *x* minutes. [/tip] 53 | -------------------------------------------------------------------------------- /docs/3-language-grammar/possessives.md: -------------------------------------------------------------------------------- 1 | # Possessives 2 | 3 | [info] **Highlight:** To form a singular possessive, add an *apostrophe-s*. [/info] 4 | 5 | A singular or plural noun is transformed to its possessive form to show its ownership or possession. 6 | To form a possessive of a singular or plural noun, add *'s* to the end of the word. This is regardless of whether the singular noun ends with an *s* or if the plural noun doesn't end with an *s*. Most plurals already end with an *s*; for these plurals, add an apostrophe at the end without an additional *s*. 7 | 8 | **Examples** 9 | 10 | **Singular nouns** 11 | - John's software 12 | - Buzz's laptop 13 | - application's password 14 | - bus's architecture 15 | - business's manager 16 | - class's description 17 | - CSS's file 18 | - OEM's product 19 | - Chris's key or Chris' key 20 | - Mr. Williams's suitcase or Mr. Williams' suitcase 21 | 22 | **Exception:** If a proper noun ends with an *s*, you can either use an apostrophe and *s* or just an apostrophe. 23 | **Exception:** The possessive of *it* is *its* and doesn't have an apostrophe. Be wary of common mistakes such as confusing *its* with *it's* (a contraction for *it is*). 24 | 25 | **Plural nouns** 26 | - computers' keyboards 27 | - buses' architecture 28 | - arrays' elements 29 | - business' earnings 30 | - classes' declaration 31 | - OEMs' products 32 | - Jones' programs 33 | - Williams' websites 34 | 35 | Don't use an apostrophe with possessive pronouns. 36 | 37 | **Examples** 38 | [warning] **Not recommended:** The website is your's. [/warning] 39 | [tip] **Recommended:** The website is yours. [/tip] 40 | 41 | ## Company-, product-, and brand-name possessives 42 | 43 | Add an apostrophe and *s* to the end of a company, product, or brand name. In general, avoid forming possessives of company, product or brand names, regardless of who owns the name. 44 | 45 | [info] **Note:** The possessive of WordPress is ***WordPress'*** [/info] 46 | 47 | **Examples** 48 | [warning] **Not recommended:** Gutenberg's features are numerous. [/warning] 49 | [tip] **Recommended:** The features of Gutenberg are numerous. [/tip] 50 | -------------------------------------------------------------------------------- /docs/3-language-grammar/prefixes-suffixes.md: -------------------------------------------------------------------------------- 1 | # Prefixes and suffixes 2 | 3 | [info] **Highlight:** Don't use three or more affixes in a single word. [/info] 4 | 5 | A *prefix* is a letter or group of letters that are attached to the beginning of a word, whereas similarly, a *suffix* is attached to the end of a word. Attaching a prefix or suffix to a word is called *affixing*. 6 | 7 | **Common suffixes** 8 | - *-able, -ible, -al, -ial, -ed, -en, -er, -er, -est, -ful, -ic, -ing, -ion, -tion, -ation, -ition, -ity, -ty, -ive, -ative, -itive, -less, -ly, -ment, , -ness, -ous, -eous, -ious, -s, -es, -y* 9 | 10 | **Common prefixes** 11 | - *anti-, de-, dis-, en-, em-, fore-, in-, im-, in-, im-, il-, ir-, inter-, mid-, mis-, non-over-, pre-, re-, semi-, sub-, super-, trans-, un-, under-* 12 | 13 | ## General do's and don'ts 14 | 15 | - Don't use three or more affixes in a single word. These words are difficult to comprehend for readers. 16 | - Some affixes such as *under, less, able, super* can be complete words too. Apart from these, make sure to use affixes along with root words rather than using them separately as individual words. 17 | - Only use hyphens when absolutely needed as most affixed words don't require hyphens. For more information and exceptions to hyphenation, see [Hyphens](https://make.wordpress.org/docs/style-guide/punctuation/hyphens/). 18 | - If you're doubtful about using a hyphen, simply ask yourself if that would simplify or impede the reader. If it impedes understanding the word or context, don't use a hyphen. Typically, hyphens are used to make longer, complicated words easier to read. 19 | -------------------------------------------------------------------------------- /docs/3-language-grammar/prepositions.md: -------------------------------------------------------------------------------- 1 | # Prepositions 2 | 3 | [info] **Highlight:** Use prepositions as needed, even at the ends of sentences. [/info] 4 | 5 | Use and place prepositions wherever necessary. It's completely fine to end a sentence with a preposition when it improves readability. Place the preposition in a reasonable position such that the reader easily understands the sentence. 6 | Avoid prepositions that complicate sentences unnecessarily. 7 | 8 | **Examples** 9 | [tip] **Recommended:** Select the block you want the text to be copied to. [/tip] 10 | [tip] **Recommended:** For further information, refer the handbook that the article links to. [/tip] 11 | [tip] **Recommended:** Find the directory that you want the content to be extracted from. [/tip] 12 | 13 | ## Prepositional phrases 14 | 15 | A prepositional phrase consists of a preposition and the words that follow it. In a prepositional phrase, the object (the following words), may be a noun, pronoun, gerund, or clause. 16 | 17 | **Example** 18 | [tip] **Recommended:** The preview shows how the page will look on the front end. [/tip] 19 | 20 | Avoid making long prepositional phrases. Long prepositional phrases are difficult to read and interpret. 21 | -------------------------------------------------------------------------------- /docs/3-language-grammar/pronouns.md: -------------------------------------------------------------------------------- 1 | # Pronouns 2 | 3 | [info] **Highlight:** Ensure that a pronoun clearly refers to its antecedent. [/info] 4 | 5 | A pronoun is a word that is used as a substitute for a noun or a noun phrase, which are contextually understood. Pronouns are used so that a particular noun isn't repeatedly used. 6 | 7 | ## Personal pronouns 8 | 9 | Avoid using personal pronouns such as *I, we, us, our,* and *ours* except in the following contexts: 10 | - Questions in FAQs. 11 | - A document whose author makes comments in the first person. 12 | - Using *we* to refer your organization or team, after using its name for the first time. 13 | 14 | Use second person (*you*) instead of first-person pronouns. 15 | 16 | ## Pronouns and genders 17 | 18 | Don't use gender-specific pronouns unless the person being referred actually uses that gender. If you're unsure which gender-specific pronoun to use, rewrite the sentence using second person (*you*). 19 | 20 | Use gender-neutral pronouns while particularly avoiding binary pronouns such as *he, him, she, her,* or renditions like *s/he, he/she,* or *(s)he*. 21 | Instead, use *they* as a gender-neutral pronoun. 22 | 23 | First try to rewrite the sentence—for example, by using the plural form, omitting the pronoun, replacing the pronoun with an article, or repeating the noun. 24 | 25 | **Examples** 26 | [warning] **Not recommended:** Contact the administrator using his or her email address. [/warning] 27 | [tip] **Recommended (Using the plural form):** Contact the administrator using their email address. [/tip] 28 | [tip] **Recommended (Omitting the pronoun):** Contact the administrator by email address. [/tip] 29 | [tip] **Recommended (Replacing pronoun with article):** Contact the administrator using an email address. [/tip] 30 | [tip] **Recommended (Repeating the noun):** Contact the administrator using the administrator's email address. [/tip] 31 | 32 | If revising a sentence isn’t feasible, use *they, their,* or *them* as a singular, gender-neutral pronoun. 33 | [warning] **Not recommended:** Once a visitor submits his or her comment, WordPress follows your preferences and either holds the comment for your approval or posts it immediately. [/warning] 34 | [tip] **Recommended:** Once a visitor submits their comment, WordPress follows your preferences and either holds the comment for your approval, or posts it immediately. [/tip] 35 | 36 | Whether used as singular or plural, *they* always takes the plural verb. 37 | [tip] **Recommended:** When visitors comment on your blog, they too get cookies stored on their computer. [/tip] 38 | 39 | For more guidelines about writing using gender-neutral pronouns, see [Writing about genders](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/#writing-about-genders) and [they, their, them](https://make.wordpress.org/docs/style-guide/word-list/t/#they-their-them). 40 | 41 | ## Relative pronouns 42 | 43 | Be careful while using relative pronouns such as *who, that*, and *which*. 44 | *That* and *which* don't mean exactly the same thing and cannot be used interchangeably. 45 | 46 | **Examples** 47 | [warning] **Not recommended:** The folder that is blue can be used. [/warning] 48 | This sentence describes a specific blue folder that can be used. *That* introduces a restrictive clause and isn't preceded by a comma. 49 | [tip] **Recommended:** The folder, which is blue can be used. [/tip] 50 | This sentence describes a blue folder from a group of folders can be used. *Which* introduces a non-restrictive clause and is preceded by a comma. 51 | 52 | Use *who* while referring to people instead of *that*. The possessive of *who*, *whose* can also be used for people, animals, and things. 53 | **Examples** 54 | [warning] **Not recommended:** Contact the developer that fixed the error. [/warning] 55 | [tip] **Recommended:** Contact the developer who fixed the error. [/tip] 56 | [tip] **Recommended:** Refer the guide whose elements are cited. [/tip] 57 | 58 | ## Pronouns and collective nouns 59 | 60 | Avoid using pronouns like *they* for collective nouns. For example, *team* would take a singular pronoun. Rewrite the sentence using the appropriate pronouns. 61 | 62 | ## Possessive pronouns 63 | 64 | Don't use an apostrophe with possessive pronouns. 65 | 66 | **Examples** 67 | [warning] **Not recommended:** The website is your's. [/warning] 68 | [tip] **Recommended:** The website is yours. [/tip] 69 | 70 | ## Ambiguities using pronouns 71 | 72 | Ensure that the pronoun you're using is referencing its antecedent (the noun that it's replacing) clearly. 73 | 74 | **Examples** 75 | [warning] **Not recommended:** Create a new post with the plugin. You can see it on the blog page. [/warning] 76 | [tip] **Recommended:** Create a new post with the plugin, You can see the post on the blog page. [/tip] 77 | [warning] **Not recommended:** The WordPress codebase can be accessed using Subversion and Git. Its repository is located at git://develop.git.wordpress.org/. [/warning] 78 | [tip] **Recommended:** The WordPress codebase can be accessed using Subversion and Git. The git repository is located at git://develop.git.wordpress.org/. [/tip] 79 | [warning] **Not recommended:** Toggle this to *on.* [/warning] 80 | [tip] **Recommended:** Toggle this button to *on.* [/tip] 81 | 82 | Use optional pronouns, such as that and who, to avoid ambiguity and clarify meaning in sentences. 83 | 84 | **Examples** 85 | [warning] **Not recommended:** Create the new post you want to see on the blog page. [/warning] 86 | [tip] **Recommended:** Create the new post that you want to see on the blog page. [/tip] 87 | [warning] **Not recommended:** Select the file you want to copy. [/warning] 88 | [tip] **Recommended:** Select the file that you want to copy. [/tip] 89 | -------------------------------------------------------------------------------- /docs/3-language-grammar/tense.md: -------------------------------------------------------------------------------- 1 | # Tense 2 | 3 | [info] **Highlight:** In general, write in present tense rather than future tense. [/info] 4 | 5 | In general, write in present tense rather than future tense. Occasionally in some cases, future tense is needed while writing about the expected behavior of something in the future. Future tense can cautiously used for highlighting a future occurrence from the reader's perspective. For example, avoid sentences like, "After clicking **Run**, you will see the updated window in 10 seconds." Additionally, sentences using present tense are easier to read and interpret than sentences that use past or future tense. Therefore, adhere to present tense, avoid future tense (*will, would*, etc.) and use it only when absolutely needed. 6 | 7 | Don't document or attempt to predict WordPress' future features, products, or services unless explicitly specified. For more information, see [Facts and claims](https://make.wordpress.org/docs/style-guide/general-guidelines/facts-claims/). 8 | 9 | **Examples** 10 | [warning] **Not recommended:** After you re-run the application, the page will update. [/warning] 11 | [tip] **Recommended:** After you re-run the application, the page gets updated. [/tip] 12 | [warning] **Not recommended:** You can enter the data in the text field. The application would then show the list. [/warning] 13 | [tip] **Recommended:** If you enter the data in the text field, the application shows the list. [/tip] 14 | [warning] **Not recommended:** If you select the block, you will be able to drag and drop it. [/warning] 15 | [tip] **Recommended:** You can drag and drop the block if you select it. [/tip] 16 | -------------------------------------------------------------------------------- /docs/3-language-grammar/verbs.md: -------------------------------------------------------------------------------- 1 | # Verbs 2 | 3 | [info] **Highlight:** Use precise verbs to write clear, succinct sentences. [/info] 4 | 5 | Use precise verbs to write clear, succinct sentences. Use active voice while writing documentation. Some exceptions for using passive voice can be made. For more information, see [Voice](https://make.wordpress.org/docs/style-guide/language-grammar/voice/). 6 | Also, write in present tense rather than future tense. For more information, see [Tense](https://make.wordpress.org/docs/style-guide/language-grammar/tense/). 7 | 8 | ## Verb forms in reference documentation 9 | 10 | For writing reference documentation to explain a procedure, phrase the procedure in terms of what the action does, not what the user/developer would do. These forms of verbs are also used in glossaries and word usage dictionaries. 11 | Usually, the only difference between the two verb forms is an *-s* at the end of the verb. An example of the verb without *-s* would be how most developers write git commits: *Add new file.* 12 | 13 | **Examples** 14 | [warning] **Not recommended:** `do_action( 'activate_header' )` : Fire before the Site Activation page is loaded. [/warning] 15 | [tip] **Recommended:** `do_action( 'activate_header' )` : Fires before the Site Activation page is loaded. [/tip] 16 | 17 | ## Verbs as nouns 18 | 19 | Don't use verbs as nouns or nouns as verbs. 20 | 21 | For more information, see [Verbs as nouns](https://make.wordpress.org/docs/style-guide/language-grammar/nouns/#verbs-as-nouns). 22 | 23 | ## Moods of verbs 24 | 25 | In general, use an indicative mood of verbs that convey a factual, friendly, and natural tone without being condescending towards the reader. 26 | 27 | **Types of verb moods** 28 | 29 | | **Mood** | **Description** | **Example** | 30 | |-------------------|--------------------------------------------------------------|------------------------------------------------------------------------------------------| 31 | | **Indicative** | Expresses factual statements, questions, and assertions. | The dashboard displays a relevant overview and summary of your website. | 32 | | **Conditional** | Expresses conditional statements; normally uses if/then. | If you click the **Preview** button, you'll see a preview of your page on the front-end. | 33 | | **Imperative** | Expresses a request, command, instructions, etc. | Click **Preview**. | 34 | | **Subjunctive** | Expresses hypothetical, non-factual, or doubtful statements. | You might need to click **Preview**. | 35 | | **Interrogative** | Expresses uncertainty, asks a question. | Do you need to click **Preview**? | 36 | 37 | Avoid using subjunctive and interrogative moods while writing documentation. Any form of uncertainty, hypothesis is confusing for the reader. Don't change moods within a sentence. 38 | -------------------------------------------------------------------------------- /docs/3-language-grammar/voice.md: -------------------------------------------------------------------------------- 1 | # Voice 2 | 3 | [info] **Highlight:** In general, use active voice rather than passive voice. [/info] 4 | 5 | In general, use active voice rather than passive voice. 6 | - When the subject (person or thing) of a sentence is performing the action, the sentence uses active voice. 7 | - When the subject (person or thing) of a sentence is being acted upon, then the sentence uses passive voice. The subject is the receiver of the action. 8 | 9 | Active voice is more effective than passive voice and reduces the word count of a sentence. In sentences using passive voice, it may be difficult inferring who or what the subject is. 10 | 11 | **Examples** 12 | [warning] **Not recommended:** A new post is created, and is shown on the blog page. [/warning] 13 | [tip] **Recommended:** Create a new post. You can see it on the blog page. [/tip] 14 | [warning] **Not recommended:** A paragraph block gets added to your page. [/warning] 15 | [tip] **Recommended:** Add a paragraph block to your page. [/tip] 16 | 17 | Sometimes passive voice may be more appropriate for a sentence. Be careful not change the meaning of a sentence while rewriting it from active voice to passive voice. 18 | 19 | Passive voice can be used when: 20 | - The object/action receiver needs to be emphasized. 21 | - If the sentence does not need a subject, or if the subject is not the focus of the sentence. 22 | - The system performs an action. 23 | - Active voice creates a cumbersome sentence structure. 24 | - You want to avoid blaming the user in cases like error messages and warnings. 25 | - You want to emphasize objects/actions in a heading or title. 26 | 27 | **Examples** 28 | [warning] **Not recommended:** You have caused an error. [/warning] 29 | [tip] **Recommended:** An error has occurred. [/tip] 30 | [tip] **Recommended:** The file is saved. [/tip] 31 | [tip] **Recommended:** The backup was created. [/tip] 32 | [tip] **Recommended:** Error 404 - Site not found. [/tip] 33 | -------------------------------------------------------------------------------- /docs/3-language-grammar/word-choice.md: -------------------------------------------------------------------------------- 1 | # Word choice 2 | 3 | [info] **Highlight:** Use common and simple technical terms that can be understood by the majority of readers. [/info] 4 | 5 | Choose words that enhance readability and increase simplicity in your documentation. 6 | For more information about writing simple, easy-to-understand documentation, see [Style, voice, and tone](https://make.wordpress.org/docs/style-guide/general-guidelines/style-voice-tone/). 7 | 8 | ## Spelling 9 | 10 | In general, use American (US) English. When the spelling of English words differ by locale, use the US spelling. 11 | If you're doubtful of a particular word, first refer the [Word list and usage dictionary](https://make.wordpress.org/docs/style-guide/word-list/); if it's not covered there, refer the [American Heritage Dictionary](https://ahdictionary.com/) and [Merriam-Webster](https://www.merriam-webster.com/). 12 | 13 | **Examples** 14 | [warning] **Not recommended:** British/Commonwealth English: aluminium, analyse, centre, colour, licence, programme, realise. [/warning] 15 | [tip] **Recommended:** American (US) English: aluminum, analyze, center, color, license, program, realize. [/tip] 16 | 17 | For an overview of locale-wise English spellings, refer the [Spelling section of Wikipedia's Manual of Style](https://wikipedia.org/wiki/Wikipedia:Manual_of_Style/Spelling). 18 | 19 | ## Technical terms 20 | 21 | Technical terms can vary from everyday words like net, bit, cloud, virus to proprietary terms such as processor, URL, website, bandwidth, that are specific to technical concepts. Many technical terms are portmanteau words - words that result from blending two or more words such as *WiFi, favicon, email, freeware,* and *webinar*. Some technical terms do become widely used and understood, but before that happens, they might be hard to understand for people who aren't familiar with them. In general, be watchful while using technical terms, so that they're only used while unmistakably communicating your message. 22 | 23 | ### General do's and don'ts for technical terms 24 | 25 | - Use common and simple technical terms that can be understood by the majority of readers. 26 | - Don't create a new term if an existing term serves its exact purpose. 27 | - If it is essential to create a new term, only do so after thoroughly verifying that the new term isn't already being used to mean something else. Also verify if your new term is comparable to existing terms with a similar meaning. 28 | - Define technical terms in your documentation. Don't assume that readers will understand them. 29 | - If you're using a particular term, customarily use it across all your documentation, publication, websites, and concepts with consistency. 30 | - Cater your vocabulary for specific audiences and readers. For example, technical terminology would apt for a developer demographic, but not for a non-technical, beginner, or business-minded audience. 31 | - Research new terminology to stay up-to-date with the latest technological terms and industry approaches. Refer the latest technical and industry publications for demonstrated uses of new terms. 32 | 33 | ## Avoid jargon and slang 34 | 35 | Be thoughtful of word choice - particularly avoid jargon, slang and ableist language. In a spoken and informal context, slang or jargon would suffice. But for achieving inclusive and accessible documentation for a global audience, slang and jargon hinders understanding more than simplifying it. Instead of using slang or jargon, use common and easy-to-understand terms. 36 | 37 | Avoid using jargon if there is a better, comprehensible word for that specific term. Additionally, don't use jargon if the term is familiar to only a small portion of your reader demographic. Only use jargon if it is absolutely needed to explain technical or software-related concepts. 38 | 39 | If you're doubtful of whether a particular term is jargon or a technical term, refer the [Word list and usage dictionary](https://make.wordpress.org/docs/style-guide/word-list/); if it isn't covered there, refer technical and industry publications for demonstration of common use. A particular term likely is jargon if you, your colleague, or reviewer thinks that it might be jargon. If the term is an [abbreviation](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/) and you're sure that your reader demographic is expected to understand the term, then you don't need to spell it out. Otherwise, spell out abbreviations. 40 | 41 | ## Avoid using common words in alternative ways 42 | 43 | Common words are known for their standard definitions that are regularly used, and are familiar with most people. Use existing words in the most widely used meaning. 44 | 45 | Don't create new ways to describe an existing word. 46 | 47 | **Examples** 48 | [warning] **Not recommended:** Don't use *data unearthing* or *data excavating* as an alternative for data mining. [/warning] 49 | [warning] **Not recommended:** The *Gutenberger* blocks are feature-packed. [/warning] 50 | [tip] **Recommended:** The blocks in Gutenberg are feature-packed. [/tip] 51 | 52 | Similarly, don't employ a totally different meaning to an existing, common word. For example, don't use *dictation* to mean command. 53 | If you have to use a word in a definition that is different from its widely used meaning, explain it with context. 54 | 55 | ## Additional resources 56 | 57 | - [Accessibility](https://make.wordpress.org/docs/style-guide/general-guidelines/accessibility/) 58 | - [Contractions](https://make.wordpress.org/docs/style-guide/language-grammar/contractions/) 59 | -------------------------------------------------------------------------------- /docs/4-punctuation/README.md: -------------------------------------------------------------------------------- 1 | # Punctuation 2 | 3 | This section provides punctuation guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/4-punctuation/apostrophes.md: -------------------------------------------------------------------------------- 1 | # Apostrophes 2 | 3 | [info] **Highlight:** Use straight apostrophes. [/info] 4 | 5 | Use straight apostrophes, the same character as a single quotation mark ('). It is completely fine to use straight apostrophes in code snippets. 6 | 7 | ## Apostrophes in contractions 8 | 9 | Use an apostrophe to indicate the letters omitted in contractions. 10 | 11 | **Examples** 12 | 13 | - *I'm - I am*. 14 | - *they've - they have*. 15 | - *don't - do not*. 16 | 17 | For more information, see [Contractions](https://make.wordpress.org/docs/style-guide/language-grammar/contractions/). 18 | 19 | ## Apostrophes in plurals 20 | 21 | Don't use apostrophes to form plurals of nouns and abbreviations. 22 | 23 | **Examples** 24 | [warning] **Not recommended:** *page's, FAQ's* [/warning] 25 | [tip] **Recommended:** *pages, FAQs* [/tip] 26 | 27 | To pluralize a number, add an *-s* at the end without any apostrophe. 28 | 29 | **Examples** 30 | [tip] **Recommended:** The 2000s [/tip] 31 | [tip] **Recommended:** Type five 7s. [/tip] 32 | 33 | Don't add an apostrophe and *s* in abbreviations of measurements to indicate plurality. For example, *50 mi* or *10 mm*; not *50 mis, 50 mi's, 10 mms*, or *10 mm's*. 34 | 35 | Avoid pluralizing symbols, signs, and individual letters by adding an apostrophe and an *s* at the end. 36 | 37 | **Examples** 38 | [warning] **Not recommended:** Invalid characters include x's, $'s, @'s, and #'s. [/warning] 39 | [tip] **Recommended:** Invalid characters include the letter *x* and the symbols $, @, and #. [/tip] 40 | 41 | For more information, see [Plurals](https://make.wordpress.org/docs/style-guide/language-grammar/plurals/). 42 | 43 | ## Apostrophes in possessives 44 | 45 | Use an apostrophe to form the possessive case of nouns. To form the possessive case of a singular noun, add an apostrophe and an *s*, even if the noun ends with an *-s, -x,* or *-z*. For plurals ending with an *-s*, add an apostrophe only. 46 | 47 | **Examples** 48 | 49 | - John's software 50 | - Buzz's laptop 51 | - application's password 52 | - bus's architecture 53 | - class's description 54 | - CSS's file 55 | - OEMs' products 56 | - business' earnings 57 | - classes' declaration 58 | - Jones' programs 59 | 60 | **Exception:** If a proper noun ends with an *s*, you can either use an apostrophe and *s* or just an apostrophe. 61 | **Exception:** The possessive of *it* is *its* and doesn't have an apostrophe. Be wary of common mistakes such as confusing *you're* (a contraction for *you are*) with *your*, and *its* with *it's* (a contraction for *it is*). 62 | 63 | Don't use an apostrophe with possessive pronouns. 64 | 65 | **Examples** 66 | [warning] **Not recommended:** The website is your's. [/warning] 67 | [tip] **Recommended:** The website is yours. [/tip] 68 | 69 | Add an apostrophe and *s* to the end of a company, product, or brand name. In general, avoid forming possessives of company, product or brand names, regardless of who owns the name. 70 | 71 | For more information, see [Possessives](https://make.wordpress.org/docs/style-guide/language-grammar/possessives/#company-product-and-brand-name-possessives). 72 | -------------------------------------------------------------------------------- /docs/4-punctuation/colons.md: -------------------------------------------------------------------------------- 1 | # Colons 2 | 3 | [info] **Highlight:** Use colons to initiate closely-related content that follows. [/info] 4 | 5 | ## Colons in introductory phrases 6 | 7 | Include a colon at the end of a phrase or sentence that list. The text preceding the colon must distinctly stand alone as a complete sentence. 8 | 9 | **Examples** 10 | [warning] 11 | **Not recommended:** 12 | The settings are: 13 | - Site title 14 | - Tagline 15 | - WordPress Address (URL) 16 | [/warning] 17 | [tip] 18 | **Recommended:** 19 | The settings that can be changed are as follows: 20 | - Site title 21 | - Tagline 22 | - WordPress Address (URL) 23 | [/tip] 24 | For more information, see [Lists](https://make.wordpress.org/docs/style-guide/formatting/lists/). 25 | 26 | ## Colons in titles and headings 27 | 28 | When you use a colon in a title or heading, capitalize the word following it. 29 | 30 | **Examples** 31 | [warning] **Not recommended:** Getting started with WordPress hooks: introduction [/warning] 32 | [tip] **Recommended:** Getting started with WordPress hooks: Introduction [/tip] 33 | [warning] **Not recommended:** Recommended settings for benchmarking: new updates this month [/warning] 34 | [tip] **Recommended:** Recommended settings for benchmarking: New updates this month [/tip] 35 | 36 | ## Colons within sentences 37 | 38 | In general, when you use a colon in a sentence, lowercase the following word. For more information, see [Capitalization](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/). 39 | 40 | **Examples** 41 | [tip] **Recommended:** Things that are encouraged: overall simplicity of the document; brief and concise sentences; and using conditional phrases. [/tip] 42 | [tip] **Recommended:** You have three options: copy the file, move it or delete it. [/tip] 43 | 44 | **Exceptions** 45 | 46 | - Capitalize the word after the colon if it is a proper noun. 47 | **Example** 48 | [tip] **Recommended:** You can install WordPress on one of the following operating systems: Windows, macOS, or Linux. [/tip] 49 | - Capitalize the word after the colon if it is a quote. 50 | **Example** 51 | [tip] **Recommended:** What does it mean if I see a message saying: "Error Code 345. Do you want to continue?" [/tip] 52 | 53 | ## Bold text preceding colon 54 | 55 | If non-italic text preceding a colon is bold, then make the colon bold too. 56 | 57 | ## Code text preceding colon 58 | 59 | Don't include a colon in text preceding code, code back-ticks (``` ` ```), or a `` tag unless it is part of the code. 60 | 61 | For more information about code formatting, see [Code examples](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/) and [Code in text](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/). 62 | 63 | ## Additional Resources 64 | 65 | - [Colons instead of dashes in lists](https://make.wordpress.org/docs/style-guide/punctuation/dashes/#colons-instead-of-dashes-in-lists) 66 | - [Code examples](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/) 67 | - [Code in text](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/) 68 | - [Lists](https://make.wordpress.org/docs/style-guide/formatting/lists/) 69 | -------------------------------------------------------------------------------- /docs/4-punctuation/commas.md: -------------------------------------------------------------------------------- 1 | # Commas 2 | 3 | [info] **Highlight:** Use commas to separate items in a series, and to separate certain kinds of clauses. Use serial commas. [/info] 4 | 5 | ## Oxford/Serial commas 6 | 7 | Use the Oxford comma before the conjunction in a series of three or more items. 8 | 9 | **Examples** 10 | [warning] **Not recommended:** Ensure that your tone is succinct, natural and friendly towards the reader. [/warning] 11 | [tip] **Recommended:** Ensure that your tone is succinct, natural, and friendly towards the reader. [/tip] 12 | 13 | ## Commas following an introductory phrase 14 | 15 | Use a comma after an introductory word or phrase. 16 | 17 | **Examples** 18 | [warning] **Not recommended:** Ultimately this simplifies the reader's comprehension. [/warning] 19 | [tip] **Recommended:** Ultimately, this simplifies the reader's comprehension. [/tip] 20 | 21 | ## Commas separating two independent clauses 22 | 23 | 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. 24 | 25 | **Examples** 26 | [warning] **Not recommended:** Copy the file, and continue.[/warning] 27 | [tip] **Recommended:** Copy the file and continue. [/tip] 28 | [warning] **Not recommended:** Either download a theme suiting your needs or use one from the preinstalled themes. [/warning] 29 | [tip] **Recommended:** Either download a theme suiting your needs, or use one that is preinstalled. [/tip] 30 | 31 | [info] **Note:** Don't use a comma to join independent clauses when you don't use a conjunction. Use a [semicolon](https://make.wordpress.org/docs/style-guide/punctuation/semicolons/#semicolons-between-two-independent-clauses) instead. [/info] 32 | 33 | **Examples** 34 | [warning] **Not recommended:** Copy the file, then continue. [/warning] 35 | [tip] **Recommended:** Copy the file; then continue. [/tip] 36 | 37 | ## Commas separating independent from dependent clauses 38 | 39 | When an independent and dependent clause are separated by a coordinating conjunction, insert a comma *only if* the sentence could be misunderstood without one. 40 | 41 | **Examples** 42 | [warning] **Not recommended:** Pages can be password protected and can only be modified by administrators. [/warning] 43 | [tip] **Recommended:** Pages can be password protected, and can only be modified by administrators. [/tip] 44 | [warning] **Not recommended:** Permalinks are permanent URLs, and their structure can be changed. [/warning] 45 | [tip] **Recommended:** Permalinks are permanent URLs and their structure can be changed. [/tip] 46 | 47 | ## Commas separating two or more adjectives in series 48 | 49 | 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. 50 | 51 | **Examples** 52 | [tip] **Recommended:** Gutenberg is a new, intuitive block-editor. [/tip] 53 | [warning] **Not recommended:** This is an enhanced, mobile UI. [/warning] 54 | [tip] **Recommended:** This is an enhanced mobile UI. [/tip] 55 | 56 | Rewrite sentences for a conversational style and tone if possible. 57 | 58 | **Examples** 59 | [tip] **Sometimes okay:** Write accessible, inclusive documentation. [/tip] 60 | [tip] **Recommended:** Write documentation that is accessible and inclusive of all readers. [/tip] 61 | 62 | ## Commas and other clauses 63 | 64 | Generally, it is beneficial to use commas for setting off specific kinds of clauses for better comprehension. 65 | - Use a comma before the word *which* at the beginning of a nonrestrictive clause. For more information, see [Relative pronouns](https://make.wordpress.org/docs/style-guide/language-grammar/pronouns/#relative-pronouns). 66 | - Put a semicolon, period, or a dash before a conjunctive adverb such as *therefore, hence, besides, however*, and insert a comma after the adverb. 67 | - Don't use a comma before the causal conjunction *because* unless it is being used at the start of a nonrestrictive clause. 68 | 69 | **Examples** 70 | [warning] **Not recommended:** Click the button which has a dropdown menu. [/warning] 71 | [tip] **Recommended:** Click the button, which has a dropdown menu. [/tip] 72 | [warning] **Not recommended:** Input the data in the field otherwise the program won't work. [/warning] 73 | [tip] **Recommended:** Input the data in the field; otherwise, the program won't work. [/tip] 74 | [warning] **Not recommended:** The command won't function, because it has been deprecated. [/warning] 75 | [tip] **Recommended:** The command won't function because it has been deprecated. [/tip] 76 | 77 | ## Commas and numbers 78 | 79 | Use a comma to separate the year when writing a complete date. Don't insert a comma between the month and year when a specific date isn't mentioned. 80 | 81 | **Examples** 82 | [warning] **Not recommended:** This article was updated in September, 2020 by the author. [/warning] 83 | [tip] **Recommended:** This article was updated in September 2020 by the author. [/tip] 84 | [warning] **Not recommended:** This article was updated on September 13 2020 by the author. [/warning] 85 | [tip] **Recommended:** This article was updated on September 13, 2020, by the author. [/tip] 86 | 87 | For more information about punctuating numbers, see [Numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/#commas-and-decimal-points-in-numbers). 88 | 89 | ## Commas with verbs in a compound predicate 90 | 91 | 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. 92 | In general, rewrite a compound predicate in two sentences, or add a subject for the second verb. 93 | 94 | **Examples** 95 | [warning] **Not recommended:** The application parses the data, and displays it in the terminal. [/warning] 96 | [tip] **Recommended:** The application parses the data. Then it displays the data in the terminal. [/tip] 97 | [tip] **Recommended:** The application parses the data, and then it displays the data in the terminal. [/tip] 98 | -------------------------------------------------------------------------------- /docs/4-punctuation/ellipses.md: -------------------------------------------------------------------------------- 1 | # Ellipses 2 | 3 | [info] **Highlight:** In general, avoid using ellipses. [/info] 4 | 5 | An *ellipsis* (plural: *ellipses*) is a set of three contiguous dots that are used to indicate omission of part of a sentence, phrase, paragraph, or content. For documentation purposes, use three periods as the dots in an ellipse, unless you use an ellipsis character. An ellipsis is also used in informal writing to connote a subsiding, hesitating, or fading expression. The word ellipsis originates from the Greek word meaning "omission". 6 | 7 | ## Using ellipses 8 | 9 | ### Punctuation and spacing 10 | 11 | Use three contiguous periods in a row while writing an ellipsis. Avoid using the ellipsis character and make use of periods in general. Insert one space before and after the ellipsis unless a punctuation mark immediately follows the ellipsis; in this case, don't insert a space after the ellipsis. 12 | 13 | **Examples** 14 | [warning] **Not recommended:** You need to wait for the post to save...and then publish the post. [/warning] 15 | [tip] **Recommended:** You need to wait for the post to save ... and then publish the post. [/tip] 16 | 17 | ### In text 18 | 19 | Don't use ellipses in your documentation. If you have to use ellipses in your documentation, rewrite your content excluding all unnecessary information while including the necessary information. Using ellipses in quoted text is acceptable, unless they appear at the beginning or the end of the text. 20 | 21 | **Examples** 22 | [warning] **Not recommended:** The WordPress Documentation handbook states "The Codex is a community-created repository for WordPress ...." [/warning] 23 | [warning] **Not recommended:** The WordPress Documentation handbook states: " ... and only a WordPress.org user account is required to create a page." [/warning] 24 | [tip] **Recommended:** The WordPress Documentation handbook states "The Codex is a community-created repository for WordPress, ... And only a WordPress.org user account is required to create a page." [/tip] 25 | 26 | #### Ending a sentence with an ellipsis 27 | 28 | When a sentence ends with an ellipsis, insert a period right after the three dots of the ellipsis, without any intervening space. This applies for ellipses both in quoted and unquoted text. 29 | 30 | **Examples** 31 | [warning] **Not recommended:** The WordPress Documentation handbook states "The Codex is a community-created repository for WordPress ...". [/warning] 32 | [warning] **Not recommended:** The Codex is a community-created repository for WordPress ... . [/warning] 33 | [tip] **Recommended:** The Codex is a community-created repository for WordPress .... [/tip] 34 | 35 | ### In a user interface 36 | 37 | Only use ellipses in user interfaces if it is absolutely needed to indicate a pause in conversational UI messages. For example, the text in a UI message might read "*Searching the database ...*". 38 | When UI elements have text with ellipses in them, exclude them from the documentation describing that UI element, unless it could cause confusion. For example, if the text in the user interface reads "*Publish ...*", document the text as "click **Publish**". 39 | 40 | ### In illustrations 41 | 42 | If required, you can use ellipses in multiple-part callouts, such as in images, illustrations, screenshots, and graphics. Insert a space before the ellipsis at the end of a phrase that continues later; and insert an ellipsis followed by a space at the beginning of a phrase that's continued from a previous phrase. If the callout ends with additional punctuation, such as a period or comma, insert a space between the punctuation mark and the ellipsis. 43 | 44 | **Example** 45 | [tip] **Recommended:** 46 | 47 | Read the instructions in the figure ... 48 | 49 | [*image*] 50 | 51 | ... and proceed to the next step. [/tip] 52 | 53 | ## Suspension points 54 | 55 | When ellipses are used to connote hesitation, a pause, or an unfinished thought, they are known as suspension points. Generally, suspension points indicate an informal, spoken language tone. Avoid using suspension points in your documentation. 56 | 57 | **Example** 58 | [warning] **Not recommended:** The package installation might not run ... but we'll see. [/warning] 59 | -------------------------------------------------------------------------------- /docs/4-punctuation/exclamation-points.md: -------------------------------------------------------------------------------- 1 | # Exclamation points 2 | 3 | [info] **Highlight:** Only use exclamation points unless absolutely needed, except in code examples. [/info] 4 | 5 | Use exclamation points in documentation unless absolutely needed. Use exclamation points sparingly except in code examples. 6 | Rather than using exclamation points to express important content, you can use [notices](https://make.wordpress.org/docs/style-guide/formatting/notices/) such as *__Warning__, __Note__,* or *__Caution__*. 7 | -------------------------------------------------------------------------------- /docs/4-punctuation/parentheses.md: -------------------------------------------------------------------------------- 1 | # Parentheses 2 | 3 | [info] **Highlight:** Use parentheses sparingly. [/info] 4 | 5 | Avoid using parentheses in standard sentences unless absolutely needed. Readers tend to overlook content inside parentheses, so avoid enclosing important information in them. Consider rephrasing your sentences even for lesser important information as well. You can use [em dashes](https://make.wordpress.org/docs/style-guide/punctuation/dashes/#em-dashes), [commas](https://make.wordpress.org/docs/style-guide/punctuation/commas/), [semicolons](https://make.wordpress.org/docs/style-guide/punctuation/semicolons/), or [periods](https://make.wordpress.org/docs/style-guide/punctuation/periods/) to provide emphasis for parenthetical phrases. 6 | 7 | ## General dos and don'ts for parentheses 8 | 9 | - When referring to a sign or symbol, introduce its spelled out version and then the sign or symbol in parentheses. 10 | **Examples**
11 | [tip] **Recommended:** Use an em dash (—) also known as a long dash, to set off a break in the flow of a sentence. [/tip] 12 | [tip] **Recommended:** End the tag with a greater than (>) symbol. [/tip] 13 | - If parentheses are introduced inside a sentence, then don't capitalize the first word even if the enclosed sentence is a complete sentence. Capitalize the first word of the sentence enclosed in parentheses if it is a proper noun. 14 | **Examples**
15 | [warning] **Not recommended:** Emphasize on the task to be accomplished (The task that you're writing about), rather than how the user should interact with the UI element. [/warning] 16 | [tip] **Recommended:** Emphasize on the task to be accomplished (the task that you're writing about), rather than how the user should interact with the UI element. [/tip] 17 | - Don't use parentheses within parentheses for text. Rephrase the sentence if necessary. 18 | - Use brackets to set off information already within parentheses. 19 | - If a complete, independent sentence is enclosed within parentheses, include the period or comma inside the parentheses. 20 | - Place colons and semicolons outside parentheses. 21 | - Place question marks and exclamation points inside the parentheses only when they're part of the parenthetical phrase. 22 | - Be watchful of misplaced, unopened, or unclosed parentheses. 23 | -------------------------------------------------------------------------------- /docs/4-punctuation/periods.md: -------------------------------------------------------------------------------- 1 | # Periods 2 | 3 | [info] **Highlight:** End all independent sentences with a period, and insert one space after the period. [/info] 4 | 5 | End all independent sentences with a period, and insert one space after the period. If the sentence or phrase ends with punctuation other than a period, such as a question mark or exclamation point, don't use a period. 6 | 7 | ## Periods with lists 8 | 9 | Ending a list item with a period depends on several factors including the kind of list the item appears in. 10 | 11 | For more information, see [Lists](https://make.wordpress.org/docs/style-guide/formatting/lists/). 12 | 13 | ### Bulleted and numbered lists 14 | 15 | In general, use a period at the end of each item in bulleted and numbered lists. 16 | 17 | **Exceptions:** Single-word items, items entirely in code font, and items with no verbs. 18 | 19 | For more information, see [Capitalization and punctuation in lists](https://make.wordpress.org/docs/style-guide/formatting/lists/#capitalization-and-punctuation). 20 | 21 | ### Description lists 22 | 23 | Don't insert a period at the end of a term, and insert a period at the end of a description. 24 | 25 | ## Periods with URLs 26 | 27 | Ending a URL or file path immediately with a period may confuse readers and even alter the URL. 28 | 29 | If the period isn't part of the URL, you can differentiate it by highlighting it different than normal text. In most browsers, a link is highlighted blue by default, which helps to differentiate it from the period. When you put a period after a URL, don't leave any space between the last character of the URL and the period. 30 | 31 | To indicate that the period ending a sentence is not a part of the URL, you can rewrite the sentence so that the URL isn't at the end. Another alternative is to exclude the period by putting the URL on a separate line other than the text. 32 | 33 | **Examples** 34 | [warning] **Not recommended:** For more information on accessibility, refer https://wordpress.org/about/accessibility/. [/warning] 35 | [warning] **Not recommended:** For more information on accessibility, refer https://wordpress.org/about/accessibility/ . [/warning] 36 | [tip] **Recommended:** For more information on accessibility, refer: 37 | https://wordpress.org/about/accessibility/ [/tip] 38 | [tip] **Recommended:** For more information on accessibility, refer https://wordpress.org/about/accessibility/ and related resources. [/tip] 39 | 40 | ## Periods with parentheses 41 | 42 | If the last part of a sentence ends within parentheses, insert the period after the closing parenthesis. If a complete, independent sentence is enclosed within parentheses, include the period inside the parentheses. 43 | 44 | **Examples** 45 | [tip] **Recommended:** You can categorize your post with multiple tags (the default tag is uncategorized). [/tip] 46 | [tip] **Recommended:** Making changes to the code while running the server could cause errors in your databases. (Specifically, it can cause corrupted tables or duplicate values.) [/tip] 47 | 48 | ## Periods with quotation marks 49 | 50 | If a sentence or phrase ends with content inside quotation marks, place the period inside the quotation marks, even if it doesn't belong in the quoted content. If the sentence or phrase inside the quotation marks ends with punctuation other than a period, such as a question mark or exclamation point, don't use a period. 51 | 52 | **Examples** 53 | [tip] **Recommended:** The developer said, "This API is the newest version." [/tip] 54 | [tip] **Recommended:** Regarding regular updates, the user asked, "When can we expect a version update?" [/tip] 55 | 56 | For more information, see [Quotation marks](https://make.wordpress.org/docs/style-guide/punctuation/quotation-marks/#quotation-marks-with-commas-and-periods). 57 | 58 | ## Periods with abbreviations 59 | 60 | Use periods at the end of shortened words. Don't use periods with acronyms and initialisms. Similarly, don't use periods with commons words that are abbreviations such as *app* or *demo*. 61 | 62 | For more information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/#periods). 63 | 64 | ## Periods with numbers 65 | 66 | Use a period to represent a decimal point. 67 | 68 | For more information, see [Numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/#commas-and-decimal-points-in-numbers). 69 | 70 | ## Periods with headings 71 | 72 | Don't end headings, subheadings, or titles with periods. 73 | 74 | For more information, see [Headings and titles](https://make.wordpress.org/docs/style-guide/formatting/headings/#formatting-headings). 75 | 76 | ## Periods with captions 77 | 78 | In general, avoid using periods with captions. 79 | 80 | For more information, see [Text associated with images](https://make.wordpress.org/docs/style-guide/formatting/media/#text-associated-with-images). 81 | -------------------------------------------------------------------------------- /docs/4-punctuation/question-marks.md: -------------------------------------------------------------------------------- 1 | # Question marks 2 | 3 | [info] **Highlight:** Use question marks sparingly. [/info] 4 | 5 | Use questions sparingly. Documentation is supposed to provide the readers with information rather than asking questions. 6 | 7 | You can ask questions from the reader's point of view. Also, it is acceptable to use questions in quoted text from user interface elements, FAQs, or reader questions. 8 | 9 | **Examples** 10 | [warning] **Not recommended:** Did you forget your password? [/warning] 11 | [tip] **Recommended:** If you forgot your password, follow these steps. [/tip] 12 | [tip] **Recommended:** What does it mean if I see a message saying: "Error Code 345. Do you want to continue?" [/tip] 13 | -------------------------------------------------------------------------------- /docs/4-punctuation/quotation-marks.md: -------------------------------------------------------------------------------- 1 | # Quotation marks 2 | 3 | [info] **Highlight:** Use straight double quotation marks. [/info] 4 | 5 | ## Quotation marks with commas and periods 6 | 7 | Place commas and periods inside quotation marks; in the American (US) English style. 8 | 9 | **Examples** 10 | [warning] **British English:** Further research is published on the homepage under the dropdown titled "Recent Findings". [/warning] 11 | [tip] **American (US) English:** Further research is published on the homepage under the dropdown titled "Recent Findings." [/tip] 12 | 13 | If punctuation is part of the quoted material, include it inside the quotation marks. 14 | 15 | **Examples** 16 | [tip] **Recommended:** What does it mean if I see a message saying: "Error Code 345. Do you want to continue?" [/tip] 17 | [tip] **Recommended:** Learn how one of the biggest nuisances online - "spam comments," are filtered out on blogs. [/tip] 18 | 19 | When you put a specific string, term, or phrase in quotation marks, put any punctuation outside the quotation marks. Don't add or remove anything from the string or term. Altering it may cause unforeseen issues or difficulties. 20 | 21 | **Examples** 22 | [warning] **Not recommended:** If you change the input field titled "password," the file needs to be updated. [/warning] 23 | [tip] **Better:** If you change the input field titled "password", the file needs to be updated. [/tip] 24 | [tip] **Recommended:** If you change the input field titled `password`, the file needs to be updated. [/tip] 25 | 26 | ## Straight and curly quotation marks 27 | 28 | The direction of curly quotation marks (“ ”) and apostrophes are often confused while writing documentation. If you use straight quotation marks (" ") the trouble of tracking and writing the starting and closing curly quotation marks is eliminated. Code specifically needs straight quotation marks for its syntax, in addition to user input fields. Furthermore, not all software environments use curly quotation marks. 29 | 30 | Hence, in general, use straight quotation marks (" "). 31 | 32 | **Examples** 33 | [warning] **Not recommended:** What does it mean if I see a message saying: “Error Code 345. Do you want to continue?” [/warning] 34 | [tip] **Recommended:** What does it mean if I see a message saying: "Error Code 345. Do you want to continue?" [/tip] 35 | 36 | ## Single quotation marks 37 | 38 | Use single quotation marks only in the following cases: 39 | - In code, where single quotation marks are used. 40 | - When you have to nest a quotation inside quotation marks. 41 | 42 | While nesting a quotation inside another quotation, use the American (US) English style, which is to use double quotation marks for the outer quotation, and single quotation marks for the inner one. 43 | 44 | **Examples** 45 | [warning] **British English:** He said, 'My colleague asked, "What does this error mean?" as he hurriedly tried to fix it.' [/warning] 46 | [tip] **American (US) English:** He said, "My colleague asked, 'What does this error mean?' as he hurriedly tried to fix it." [/tip] 47 | -------------------------------------------------------------------------------- /docs/4-punctuation/semicolons.md: -------------------------------------------------------------------------------- 1 | # Semicolons 2 | 3 | [info] **Highlight:** Use semicolons to separate independent clauses. [/info] 4 | 5 | Generally, sentences with semicolons are complicated and are often difficult to comprehend for readers. Try to simplify sentences containing semicolons by rephrasing, splitting, or itemizing them. In general, use semicolons judiciously. 6 | 7 | ## Semicolons between two independent clauses 8 | 9 | Use a semicolon between two closely associated independent clauses that aren't joined by a conjunction, where a comma or period isn't quite pertinent. 10 | 11 | **Examples** 12 | [tip] **Recommended:** Upload the file; then click **Continue**. [/tip] 13 | [tip] **Recommended:** There are multiple different block types that are available; a list of blocks can be found [here](https://wordpress.org/support/article/blocks/). [/tip] 14 | 15 | ## Semicolons before an independent clause 16 | 17 | Use a semicolon before an independent clause that is set off with phrases such as *for example, that is, in particular*, or *to illustrate*. 18 | 19 | **Examples** 20 | [tip] **Recommended:** The preview shows how the page will look on the front end; that is, the final published website. [/tip] 21 | [tip] **Recommended:** Making changes to the code while running the server could cause errors in your databases; specifically, corrupted tables or duplicate values. [/tip] 22 | 23 | ## Semicolons before a conjunctive adverb 24 | 25 | Insert a semicolon before conjunctive adverbs that join two independent clauses. Examples of commonly used conjunctive adverbs include *accordingly, additionally, also, besides, consequently, finally, furthermore, hence, however, indeed, in fact, likewise, similarly, therefore*, and *thus*. 26 | 27 | **Examples** 28 | [tip] **Recommended:** You can drag and drop the block if you select it; similarly, you can also use the **Move Up** and **Move Down** buttons to move the block. [/tip] 29 | [tip] **Recommended:** After you re-run the application, the page gets updated; however, you'll need to refresh the page in the browser too. [/tip] 30 | 31 | ## Semicolons between contrasting statements 32 | 33 | Use a semicolon between two contrasting statements that aren't joined by a conjunction. 34 | 35 | **Example** 36 | [tip] **Recommended:** You don't need top specs to run WordPress locally; a simple configuration would be totally adequate. [/tip] 37 | 38 | ## Semicolons in a series 39 | 40 | When you have separate items in a series that contain their own punctuation such as commas or periods, use semicolons to separate out the complex series. You can also segregate the series into a list. 41 | 42 | **Examples** 43 | [tip] **Recommended:** 44 | 45 | Here’s the quick version of the instructions for those who are already comfortable with performing such installations: download and unzip the WordPress package if you haven’t already; create a database for WordPress on your web server, as well as a MySQL (or MariaDB) user who has all privileges for accessing and modifying it; (optional) find and rename `wp-config-sample.php` to `wp-config.php`, then edit the file and add your database information; upload the WordPress files to the desired location on your web server; run the WordPress installation script by accessing the URL in a web browser. 46 | [/tip] 47 | [tip] **Recommended:** 48 | 49 | Here’s the quick version of the instructions for those who are already comfortable with performing such installations: 50 | - Download and unzip the WordPress package if you haven’t already. 51 | - Create a database for WordPress on your web server, as well as a MySQL (or MariaDB) user who has all privileges for accessing and modifying it. 52 | - (Optional) Find and rename `wp-config-sample.php` to `wp-config.php`, then edit the file and add your database information. 53 | - Upload the WordPress files to the desired location on your web server. 54 | - Run the WordPress installation script by accessing the URL in a web browser. 55 | [/tip] 56 | -------------------------------------------------------------------------------- /docs/4-punctuation/slashes.md: -------------------------------------------------------------------------------- 1 | # Slashes 2 | 3 | [info] **Highlight:** Avoid using slashes except in code examples, file paths, and URLs. [/info] 4 | 5 | In general, try to avoid slashes in your documentation, except in code examples, file paths, and URLs. 6 | 7 | ## Slashes with combinations 8 | 9 | Use a slash to indicate a combination. Capitalize the second word if the first word in the combination is capitalized. 10 | 11 | **Examples** 12 | [tip] **Recommended:** Toggle the on/off switch on the dashboard. [/tip] 13 | [tip] **Recommended:** Toggle the On/Off switch on the dashboard. [/tip] 14 | [tip] **Recommended:** The UI/UX for the plugin was recently updated. [/tip] 15 | [tip] **Recommended:** The website can be developed with HTML/CSS as well. [/tip] 16 | 17 | ## Slashes with alternatives 18 | 19 | Don't use slashes to separate alternatives. Don't substitute a slash for the words *and* or *or*. 20 | 21 | **Examples** 22 | [warning] **Not recommended:** You can install the plugin by uploading/searching in the directory. [/warning] 23 | [tip] **Recommended:** You can install the plugin by uploading it, or searching it in the directory. [/tip] 24 | [warning] **Not recommended:** The user must have administrator/editor access to publish the post. [/warning] 25 | [tip] **Recommended:** The user must have administrator or editor access to publish the post. [/tip] 26 | [tip] **Recommended:** The user must have administrator and editor access to publish the post. [/tip] 27 | [warning] **Not recommended:** Repeat the process 2/3 times until you get a favorable result. [/warning] 28 | [tip] **Recommended:** Repeat the process 2 or 3 times until you get a favorable result. [/tip] 29 | [tip] **Recommended:** Repeat the process 2 to 3 times until you get a favorable result. [/tip] 30 | 31 | ## Slashes with URLs 32 | 33 | Use slashes in URLs, local, and internet addresses. Use two slashes after the protocol name. 34 | 35 | **Examples** 36 | [tip] **Recommended:** Navigate to http://localhost/wordpress to start the WordPress install. [/tip] 37 | [tip] **Recommended:** Visit https://make.wordpress.org/docs/style-guide/ for additional information.[/tip] 38 | [tip] **Recommended:** The uploaded file can be found on ftp://example.com/uploads. [/tip] 39 | 40 | ## Slashes with file paths and names 41 | 42 | Use forward slashes in computer, server, folder, and file names and paths. For Microsoft Windows file paths and names, use backslashes. 43 | 44 | **Examples** 45 | [tip] **Recommended:** Download the zip file, and extract it into the web directory for your WAMP (Windows) installation: `C:\wamp\www`. [/tip] 46 | [tip] **Recommended:** Open the WordPress configuration file: `/var/www/wordpress/wp-config.php`. [/tip] 47 | 48 | ## Slashes with fractions and mathematical equations 49 | 50 | Don't use slashes with fractions, as they may be difficult to comprehend. Using slashes with fractions could be misunderstood as alternatives or combinations. 51 | 52 | **Examples** 53 | [warning] **Not recommended:** 3/4 [/warning] 54 | [tip] **Recommended:** ¾ [/tip] 55 | [tip] **Recommended:** 0.75 [/tip] 56 | [tip] **Recommended:** 75% [/tip] 57 | 58 | Be cautious while using slashes between the numerator and denominator in mathematical equations. 59 | 60 | **Examples** 61 | [tip] **Sometimes okay:** x/2 = 4 [/tip] 62 | [tip] **Sometimes okay:** (x+2)/8 = 2/3 [/tip] 63 | 64 | ## Slashes with abbreviations 65 | 66 | Don't use abbreviations utilizing slashes. Instead, spell the abbreviation out. 67 | 68 | **Examples** 69 | [warning] **Not recommended:** *b/c, w/o, w/, c/o, a/c* [/warning] 70 | [tip] **Recommended:** because, without, with, care of, account [/tip] 71 | 72 | ## Slashes with dates 73 | 74 | Don't use date formats with slashes. 75 | 76 | For more information, see [Dates and times](https://make.wordpress.org/docs/style-guide/formatting/dates-times/#things-to-avoid-while-expressing-dates). 77 | -------------------------------------------------------------------------------- /docs/5-formatting/README.md: -------------------------------------------------------------------------------- 1 | # Formatting 2 | 3 | This section provides formatting guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/5-formatting/examples.md: -------------------------------------------------------------------------------- 1 | # Examples and scenarios 2 | 3 | [info] **Highlight:** Write unbiased examples without revealing personally identifiable information. [/info] 4 | 5 | Providing examples in documentation helps the reader visualize concepts. Be thoughtful while writing and coming up with fictitious examples and scenarios; sometimes they may be unintentionally biased. As well as writing diverse and inclusive documentation, don't reveal personally identifiable information such as real names, addresses, phone numbers, email addresses, or financial information. In addition to fictitious examples and scenarios, you can also use [placeholder variables](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/#placeholder-variables) such as EMAIL_ADDRESS or PHONE_NUMBER. 6 | 7 | In general, write examples and scenarios with a global perspective. Some scenarios may be improbable in some regions, and some may be different altogether. Social customs, politics, events, holidays, sports, traditions, religion, and legal and business practices vary worldwide. Avoid discussing technologies and standards that aren't adopted worldwide; don't assume US standards are familiar to everyone. Be thoughtful on how these fictional scenarios would be perceived by a global audience. 8 | 9 | For more information, see [Writing inclusive documentation](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/) and [Writing documentation for an international audience](https://make.wordpress.org/docs/style-guide/general-guidelines/global-audience/). 10 | 11 | ## Example domain names 12 | 13 | While writing a generic domain name in an example, use example.com, example.org, or example.net. 14 | 15 | ## Example email addresses 16 | 17 | For example email addresses, use one of the domains listed in [Example domain names](#example-domain-names). 18 | 19 | **Example** 20 | [tip] **Recommended:** name@example.com [/tip] 21 | 22 | ## Example person names 23 | 24 | When you need people's names and their activities in an example, use fictional character names from non-copyrighted material. Don't use character names from copyrighted content such as movies, television shows, or books. Also, don't use real people's names. 25 | 26 | If you can't think of a fictional character name that is not copyrighted, you can invent new names; although be thoughtful while thinking of new names. Ensure a diverse, [inclusive](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/), and [global](https://make.wordpress.org/docs/style-guide/general-guidelines/global-audience/) demographic while writing examples with people's names. 27 | 28 | If another guideline specifically defines fictional person names, use those names in your examples. 29 | 30 | ## Example organization names 31 | 32 | When you need an organization name in an example, use *Example Organization*. If you need multiple organization names or need to differentiate between two fictional companies, add a description to the organization names. For example, you can use *Example Tech Organization* and *Example Education Organization*. 33 | 34 | ## Example phone numbers 35 | 36 | Don't use real phone numbers in examples. 37 | 38 | For phone number examples according to the [North American Numbering Plan](https://make.wordpress.org/docs/style-guide/formatting/phone-numbers/#north-american-phone-numbers), use a US number in the range (800) 555-0100 through (800) 555-0199. That range is reserved for use in examples and in fiction. 39 | 40 | For international phone number examples, use a US number from the same range and include the country and area codes. For more information about phone number formatting, see [Phone numbers](https://make.wordpress.org/docs/style-guide/formatting/phone-numbers/). 41 | 42 | **Examples** 43 | [tip] **Recommended:** (800) 555-0139 [/tip] 44 | [tip] **Recommended:** +1 800 555 0139 [/tip] 45 | 46 | ## Example IP addresses 47 | 48 | For IPv4 examples, use one of the [RFC 5737](https://tools.ietf.org/html/rfc5737) addresses reserved for documentation purposes. These addresses are not used on the internet. The use the following three reserved IPv4 addresses: 49 | - `192.0.2.1` 50 | - `198.51.100.1` 51 | - `203.0.113.1` 52 | 53 | For IPv4 address ranges, use the following examples: 54 | - `192.0.2.0/24` 55 | - `198.51.100.0/24` 56 | - `203.0.113.0/24` 57 | 58 | When you need an IPv6 address example, use values from the [RFC 3849](https://tools.ietf.org/html/rfc3849) range as follows: 59 | - `2001:db8::` 60 | - `2001:db8:ffff:ffff:ffff:ffff:ffff:ffff` 61 | - `2001:db8:1:1:1:1:1:1` 62 | - `2001:db8:2:2:2:2:2:2` 63 | - `2001:db8:3:3:3:3:3:3` 64 | - `2001:db8:4:4:4:4:4:4` 65 | 66 | For IPv6 address ranges, use the following example: 67 | - `2001:db8::/32` 68 | 69 | ## Example street addresses 70 | 71 | Use different locales and regions, and avoid using real street addresses in examples. Instead, use the following fictional street address: 72 | 73 | 1000 99th Street
74 | San Francisco, CA 94110
75 | United States of America 76 | -------------------------------------------------------------------------------- /docs/5-formatting/filenames.md: -------------------------------------------------------------------------------- 1 | # Filenames, file formats, and types 2 | 3 | [info] **Highlight:** Use all-lowercase filenames and separate words in filenames with hyphens. [/info] 4 | 5 | ## Naming files 6 | 7 | Use lowercase file, folder, and directory names. In general, separate words in filenames with hyphens, not underscores. Use standard [ASCII alphanumeric characters](https://wikipedia.org/wiki/ASCII#Character_set) in file, folder, and directory names. 8 | 9 | ### Consistent naming 10 | 11 | If you're creating and naming new files where other files have a different naming convention, see if the other files and folders can be renamed with the aforementioned guidelines. If you cannot change existing filenames, it is acceptable to use underscores or other naming conventions that are in use, to remain consistent with the existing style. 12 | 13 | For example, if the directory already has files named as `theme_1.php`, `theme_2.php`, and `theme_3.php`, it's acceptable to name the new file as `theme_4.php` instead of `theme-4.php`. 14 | 15 | **Examples** 16 | [warning] **Not recommended:** `newcache.php`, `newCache.php`, `new-caché.php` [/warning] 17 | [tip] **Recommended:** `new-cache.php` [/tip] 18 | [tip] **Sometimes okay:** `new_cache.php` [/tip] 19 | [warning] **Not recommended:** `wpsettings1.php`, `wpSettings1.php`, `WPSettings1.php`, `wp-settings1.php`, `wpsettings-1.php` [/warning] 20 | [tip] **Recommended:** `wp-settings-1.php` [/tip] 21 | [tip] **Sometimes okay:** `wp_settings_1.php` [/tip] 22 | 23 | It's acceptable to have some inconsistency in file and folder names if it can't be avoided otherwise. There might be predefined design and style guidelines or undocumented guidelines that are already in use. Sometimes, file naming can also be automated by the product. In those cases, it's okay to make exceptions for those files. 24 | 25 | ## Referring to files 26 | 27 | ### Referring to filenames 28 | 29 | While referring to a file, follow these guidelines: 30 | 31 | - Use [code font](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/). 32 | - Use the exact name of the file, even if it doesn't follow the [file naming guidelines](#naming-files). 33 | - If content from the file is included in the page, follow the [code example](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/) guidelines and precede the code sample or content with an introductory statement that states the filename. 34 | 35 | **Example** 36 | [tip] **Recommended:** In the following `styles.css` file, set the `opacity` to 0.75: [/tip] 37 | 38 | ### File interactions 39 | 40 | While writing about file interactions, don't use the file types as a verb. 41 | 42 | **Examples** 43 | [warning] **Not recommended:** Unzip the file. [/warning] 44 | [warning] **Not recommended:** Unzip the zip file. [/warning] 45 | [tip] **Recommended:** Extract the zip file. [/tip] 46 | 47 | ### Referring to file types 48 | 49 | Use the formal file type instead of the file extension while referring to file types. Many file types are expressed in uppercase, as they are acronyms or initialisms. 50 | 51 | **Examples** 52 | [warning] **Not recommended:** a `.css` file [/warning] 53 | [tip] **Recommended:** a CSS file [/tip] 54 | [warning] **Not recommended:** a `.py` file [/warning] 55 | [tip] **Recommended:** a Python file [/tip] 56 | 57 | The following table lists filename extensions and the corresponding file type names to use: 58 | 59 | | **Extension** | **File type name** | 60 | |-----------------|--------------------| 61 | | `.css` | CSS file | 62 | | `.csv` | CSV file | 63 | | `.dmg` | DMG file | 64 | | `.exe` | executable file | 65 | | `.gif` | GIF file | 66 | | `.html` | HTML file | 67 | | `.img` | disk image file | 68 | | `.jar` | JAR file | 69 | | `.java` | Java file | 70 | | `.jpg`, `.jpeg` | JPEG file | 71 | | `.js` | JavaScript file | 72 | | `.json` | JSON file | 73 | | `.md` | Markdown file | 74 | | `.mp3` | MP3 file | 75 | | `.mp4` | MP4 file/MPEG-4 file | 76 | | `.pdf` | PDF file | 77 | | `.php` | PHP file | 78 | | `.png` | PNG file | 79 | | `.ps` | PowerShell file | 80 | | `.py` | Python file | 81 | | `.rar` | RAR file | 82 | | `.sh` | Bash file | 83 | | `.sql` | SQL file | 84 | | `.svg` | SVG file | 85 | | `.tar` | tar file | 86 | | `.txt` | text file | 87 | | `.wav` | WAV file | 88 | | `.xml` | XML file | 89 | | `.yaml`, `.yml` | YAML file | 90 | | `.zip` | zip file | 91 | -------------------------------------------------------------------------------- /docs/5-formatting/footnotes.md: -------------------------------------------------------------------------------- 1 | ## Footnotes 2 | 3 | [info] **Highlight:** Avoid writing footnotes in documentation. [/info] 4 | 5 | A footnote is an annotation provided at the end of a paragraph, chapter, or a page with additional information related to the content. 6 | Rather than using a footnote, you can use a [note](https://make.wordpress.org/docs/style-guide/formatting/notices/#cautions-warnings-notes-and-other-notices), a [link](https://make.wordpress.org/docs/style-guide/linking/link-text/), use [parentheses](https://make.wordpress.org/docs/style-guide/punctuation/parentheses/), or [dashes](https://make.wordpress.org/docs/style-guide/punctuation/dashes/). 7 | 8 | If there is no alternative than using a footnote, then use a symbol instead of a number. Use the symbols: *, †, ‡, §, ‖, ¶ - preferably in that order. 9 | 10 | **Examples** 11 | [warning] **Not recommended:** The image needs to be high resolution.1 [/warning] 12 | [tip] **Recommended:** The image needs to be high resolution.* 13 | 14 | *Footnote content at the end of the page. [/tip] 15 | -------------------------------------------------------------------------------- /docs/5-formatting/headings.md: -------------------------------------------------------------------------------- 1 | # Headings and titles 2 | 3 | [info] **Highlight:** Use sentence case for headings, and follow proper heading hierarchy. [/info] 4 | 5 | Headings provide proper content structure and visual points for readers to scan and navigate through content on any page. The heading hierarchy, along with other formatting such as spacing, lists, and illustrations helps break up long walls of text into a readable structure. It is also easier to jump between sections or pages if the headings and titles stand out. 6 | 7 | In general, use consistent and descriptive headings and titles in any type of content. 8 | 9 | ## Formatting headings 10 | 11 | - Use sentence case capitalization for headings and titles. For more information, see [Capitalization in titles and headings](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/#capitalization-in-titles-and-headings). 12 | - When using abbreviations in headings, spell out and declare the abbreviation in the succeeding body text. For more information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/#spelling-out-and-declaring-abbreviations). 13 | - Don't end headings with a period. Avoid using other punctuation at the end of headings unless absolutely necessary. 14 | **Examples**
15 | [tip] **Sometimes okay:** Still have questions? [/tip] 16 | - Tag headings using heading elements. For HTML use `

`, `

`, and so on. In markdown use `#`, `##`, and so on. 17 | - Use proper heading hierarchy. 18 | - Use a level-1 heading for the page title or heading of the main content. A level-1 heading is built into heading styles in many web pages and site themes. 19 | - Don't skip the heading levels of the heading hierarchy. 20 | **Examples**
21 | [warning] **Not recommended:** 22 | ```markdown 23 | # Design Decisions 24 | This page lists a number of important design decisions that come up frequently. 25 | ### Absolute versus relative URLs 26 | ``` 27 | [/warning] 28 | [tip] **Recommended:** 29 | ```markdown 30 | # Design Decisions 31 | This page lists a number of important design decisions that come up frequently. 32 | ## Absolute versus relative URLs 33 | ``` 34 | [/tip] 35 | - Don't use empty headings or headings with no associated content. 36 | **Examples**
37 | [warning] **Not recommended:** 38 | ```markdown 39 | # Design Decisions 40 | ## Absolute versus relative URLs 41 | ``` 42 | [/warning] 43 | [tip] **Recommended:** 44 | ```markdown 45 | # Design Decisions 46 | This page lists a number of important design decisions that come up frequently. 47 | ## Absolute versus relative URLs 48 | ``` 49 | [/tip] 50 | - Use CSS to alter the style, formatting, or irregular heading hierarchy rather than altering the heading elements or creating new formatting. Ensure that heading markup is not used for presentational purposes. 51 | - Avoid using code items in headings when possible. If using a code item in a heading is absolutely necessary, add a descriptive noun to the item in code font. For more information, see [Keywords](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/#keywords). 52 | - Don’t add extra functionality inside a heading, like links or buttons. 53 | - Break two-line headings carefully. In a non-responsive design, when the heading exceeds one line, break it so that the text is appropriately balanced. In responsive designs, the content is dynamically fit to the screen. 54 | - Break the line at the end of a phrase, if possible. 55 | - Break the line after punctuation. 56 | - Keep prepositions and adjectives on the same line, along with the words they modify. 57 | - Keep hyphenated words and multiple-word proper nouns (such as *Sunset Beach*) on the same line. 58 | - If none of these alternatives work, rewrite or rephrase the headline to the proper specifications. 59 | - Ensure that your headings stand out with vertical spacing. Heading typically have more vertical space and less space below them. This helps distinguish the heading and associate it with the following text or content. Heading spacing is built into heading styles in most web pages and site themes; use those styles to control the spacing in a consistent manner. 60 | - Don't use extra line breaks or other formatting to increase heading spacing. Doing so may cause difficulties while viewing responsive webpages, specifically on mobile devices - where the layout is adjusted to the screen size automatically. 61 | 62 | ## Writing headings 63 | 64 | - Consider headings as an outline of its succeeding content. If the readers don't read the headings, they probably won't read the accompanying content. 65 | - Level-1 headings are supposed to convey the principal essence of the topic being discussed in the following body content. 66 | - If there is a lot of content to include in the primary heading, consider using secondary-level headings to break up content. 67 | - Ensure that every new heading introduces a different and specific topic than earlier headings in a heading hierarchy. 68 | - Write short and succinct headings and put the most important idea at the beginning. Focus on the information that the readers need to know. 69 | - Be specific with your headings. You can write more specific headings as you move further down the heading hierarchy. 70 | - Consider using phrases in action + object form and gerund form in headings. Examples of such phrases include *Write about genders, Writing about genders, Use diverse examples*, and *Using diverse examples*. 71 | - Avoid using hyphens (-), ampersands (&), and other symbols in headings. 72 | 73 | ## Referring to subsections 74 | 75 | While referring to subheadings or subsections in a document or a page, use phrases such as *in the following section* or *in the aforementioned section*. Don't use ambiguous phrases such as *in these sections* or *in this section*. 76 | -------------------------------------------------------------------------------- /docs/5-formatting/key-terms.md: -------------------------------------------------------------------------------- 1 | # Key terms 2 | 3 | [info] **Highlight:** Use italics to emphasize or introduce a particular word or phrase in your content. [/info] 4 | 5 | When you need to accentuate or emphasize a particular word or phrase in your content, such as when introducing or discussing a new concept or a new word, use italics. 6 | 7 | **Examples** 8 | [warning] **Not recommended:** An administrator’s tool of sorts, "phpMyAdmin" is a PHP script meant for giving users the ability to interact with their MySQL databases. [/warning] 9 | [warning] **Not recommended:** An administrator’s tool of sorts, **phpMyAdmin** is a PHP script meant for giving users the ability to interact with their MySQL databases. [/warning] 10 | [tip] **Recommended:** An administrator’s tool of sorts, *phpMyAdmin* is a PHP script meant for giving users the ability to interact with their MySQL databases. [/tip] 11 | -------------------------------------------------------------------------------- /docs/5-formatting/notices.md: -------------------------------------------------------------------------------- 1 | # Notices 2 | 3 | [info] **Highlight:** Use notices to warn, alert, notify, or provide useful information to readers. [/info] 4 | 5 | ## Cautions, warnings, notes, and other notices 6 | 7 | To warn, alert, notify, or provide useful information to the reader that isn't part of the flow of text or needs to be highlighted, use one of the following notice types: 8 | 9 | - **Note** or **Info** 10 | Use this notice type for an informational note or message with the `[ info ][ /info ]` (without spaces) short code. 11 | 12 | **Example** 13 | [info] **Note:** “Wide width” and “Full width” alignment need to be enabled by the theme of your site. [/info] 14 | 15 | - **Tip** 16 | Use this notice type to highlight tips and recommended actions with the `[ tip ][ /tip ]` (without spaces) short code. 17 | 18 | **Example** 19 | [tip] **Tip:** You can use the slash command to insert a new block. [/tip] 20 | 21 | - **Caution** or **Alert** 22 | Use this notice type to suggest readers to proceed with caution and alert them to important messages with the `[ alert ][ /alert ]` (without spaces) short code. 23 | 24 | **Example** 25 | [alert] **Caution:** Using a deprecated version may cause different outcomes. [/alert] 26 | 27 | - **Warning** 28 | When something is particularly precarious use this notice type with the `[ warning ][ /warning ]` (without spaces) short code. A warning is generally stricter and more rigid than a caution. 29 | 30 | **Example** 31 | [warning] **Warning:** Making changes to the code while running the server could cause errors in your databases; specifically, corrupted tables or duplicate values. [/warning] 32 | 33 | - **Tutorial** or **Step** 34 | Use this notice type to indicate a step or procedure in a tutorial with the `[ tutorial ][ /tutorial ]` (without spaces) short code. 35 | 36 | **Example** 37 | [tutorial] **Step:** Move the selected file to this folder. [/tutorial] 38 | 39 | Avoid grouping two or more notices together. Consider rewriting or rearranging the content to avoid confusion. 40 | 41 | For more information about short codes and code examples, see [Code examples](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/) and [Syntax highlighting short codes](https://plugins.trac.wordpress.org/browser/syntaxhighlighter/trunk/syntaxhighlighter.php#L173). 42 | 43 | ## Other formatting style for notices 44 | 45 | If your website or page uses a different standardized formatting style for notices, you can supersede the aforementioned formatting style. 46 | -------------------------------------------------------------------------------- /docs/5-formatting/obsolete-content.md: -------------------------------------------------------------------------------- 1 | # Obsolete content 2 | 3 | [info] **Highlight:** Use a warning notice type to mark content as outdated. [/info] 4 | 5 | As WordPress develops and evolves systematically, some methods and technologies change, which may outdate documentation. Accurately identifying and marking outdated content is beneficial for updating and maintaining up-to-date documentation for readers. 6 | 7 | ## Types of obsolete content 8 | 9 | Obsolete content can be determined by the following contexts: 10 | - A whole page or article is outdated. 11 | - A section from a page or article is outdated. 12 | - A specific part of a section, page, or article is outdated. 13 | 14 | ## Marking content as obsolete 15 | 16 | ### Outdated page 17 | 18 | Use a **Warning** [notice type](https://make.wordpress.org/docs/style-guide/formatting/notices/#cautions-warnings-notes-and-other-notices) to mark a page as obsolete, by enclosing the following phrase inside the `[warning][/warning]` short code: 19 | *__Warning:__ This page is outdated as of WordPress VERSION. It is maintained for archival purposes only.* 20 | 21 | Replace VERSION with the WordPress version since the page was marked obsolete. 22 | 23 | **Example** 24 | [tip] **Recommended (Markdown):** `[warning] **Warning:** This page is outdated as of WordPress 5.5.2. It is maintained for archival purposes only. [/warning]` [/tip] 25 | 26 | ### Outdated section from a page or article 27 | 28 | Use a **Warning** [notice type](https://make.wordpress.org/docs/style-guide/formatting/notices/#cautions-warnings-notes-and-other-notices) to mark a section from a page as obsolete, by enclosing the following phrase inside the `[warning][/warning]` short code: 29 | *__Warning:__ The SECTION_NAME section is outdated as of WordPress VERSION. It is maintained for archival purposes only.* 30 | 31 | Replace SECTION_NAME with the title, heading, subheading, or description of the outdated section. Replace VERSION with the WordPress version since the page was marked obsolete. 32 | 33 | **Example** 34 | [tip] **Recommended (Markdown):** `[warning] **Warning:** The *Installation* section is outdated as of WordPress 4.3. It is maintained for archival purposes only. [/warning]` [/tip] 35 | 36 | ### Outdated part of a section, page, or article 37 | 38 | Use a **Warning** [notice type](https://make.wordpress.org/docs/style-guide/formatting/notices/#cautions-warnings-notes-and-other-notices) to mark specific content of a section as obsolete, by enclosing the following phrase inside the `[warning][/warning]` short code: 39 | *__Warning:__ The following content on SECTION_NAME is outdated as of WordPress VERSION. It is maintained for archival purposes only.* 40 | 41 | Replace SECTION_NAME with the title, heading, subheading, or description of the outdated part. Replace VERSION with the WordPress version since the page was marked obsolete. 42 | 43 | **Example** 44 | [tip] **Recommended (Markdown):** `[warning] **Warning:** The following content on *i18n in JavaScript* is outdated as of WordPress 5.0. It is maintained for archival purposes only. [/warning]` [/tip] 45 | 46 | ## Adding updated documentation 47 | 48 | Use an **Info** notice type and add a URL of updated documentation, if any. 49 | - If the updated information can be found on another page, enclose the following notice inside the `[info][/info]` short code: 50 | *__Note:__ Updated information can be found on PAGE_URL.* 51 | Replace PAGE_URL with the URL of the updated documentation. 52 | - If the page was moved to another destination, enclose the following notice inside the `[info][/info]` short code: 53 | *__Note:__ This page was moved to PAGE_URL.* 54 | Replace PAGE_URL with the URL of the new destination. 55 | 56 | **Examples** 57 | [tip] **Recommended (Markdown):** 58 | `[warning] **Warning:** The following content on *i18n in JavaScript* is outdated as of WordPress 5.0. It is maintained for archival purposes only. [/warning]` 59 | `[info] **Note:** Updated information can be found on https://developer.wordpress.org/block-editor/developers/internationalization/#how-to-use-i18n-in-javascript. [/info]` [/tip] 60 | [tip] **Recommended (Markdown):** 61 | `[warning] **Warning:** This page is outdated as of WordPress 5.5.2. It is maintained for archival purposes only. [/warning]` 62 | `[info] **Note:** This page was moved to http://developer.wordpress.org/reference. [/info]` [/tip] 63 | -------------------------------------------------------------------------------- /docs/5-formatting/phone-numbers.md: -------------------------------------------------------------------------------- 1 | # Phone numbers 2 | 3 | [info] **Highlight:** Use mock phone numbers instead of real ones in examples. Follow proper formatting for phone numbers. [/info] 4 | 5 | ## Phone numbers in examples 6 | 7 | Use mock phone numbers instead of real ones in examples. For more information about what phone numbers to use in examples, see [Example phone numbers](https://make.wordpress.org/docs/style-guide/formatting/examples/#example-phone-numbers). 8 | 9 | ## Writing real phone numbers 10 | 11 | If you're providing a real phone number to contact a real individual or organization, use the following formats to write them. 12 | 13 | ### North American phone numbers 14 | 15 | To format phone numbers in the USA, Canada, and other [NANP](https://wikipedia.org/wiki/North_American_Numbering_Plan) (North American Numbering Plan) countries, enclose the area code in parentheses, insert a space, and then hyphenate the three-digit exchange code with the four-digit number. 16 | 17 | **Example** 18 | [tip] **Recommended:** (800) 555-0139 [/tip] 19 | 20 | ### International phone numbers 21 | 22 | To format phone numbers in non-NANP countries, include the country and area codes at the beginning of the phone number. Insert a plus sign before the country code without any space in between. The plus sign (+) stands in for a prefix known as an *exit code* that lets you dial out of a country. Separate the groups of numbers with spaces. 23 | 24 | **Example** 25 | [tip] **Recommended:** +91 000 555 0139 [/tip] 26 | -------------------------------------------------------------------------------- /docs/5-formatting/trademarks.md: -------------------------------------------------------------------------------- 1 | # Trademarks 2 | 3 | [info] **Highlight:** Follow the trademark, licensing, and citation guidelines provided by the owners of the respective marks. [/info] 4 | 5 | For trademark marking or attribution in documentation, follow the trademark, licensing, and citation guidelines provided by the owners of the respective marks. Categories include registered trademarks (®), trademarks (™), registered service marks (®), and service marks (℠). 6 | 7 | For additional information about WordPress trademarks, see the [Trademark Policy for WordPress](https://wordpressfoundation.org/trademark-policy/). 8 | 9 | ## Using trademarks 10 | 11 | Always use trademarked terms as adjectives. Don't use trademarked terms in verb or noun forms. If a trademark is more than one word, don’t break it across multiple lines of text; instead, use a nonbreaking space in between. 12 | 13 | ## Plural forms of trademarks 14 | 15 | In general, avoid forming plural forms of company, product, or brand names, regardless of who owns the name. 16 | 17 | For more information about plural forms, see [Plurals](https://make.wordpress.org/docs/style-guide/language-grammar/plurals/). 18 | 19 | ## Possessive forms of trademarks 20 | 21 | In general, avoid forming possessives of company, product, or brand names, regardless of who owns the name. 22 | 23 | For more information about possessive forms of trademarks, see [Company-, product-, and brand-name possessives](https://make.wordpress.org/docs/style-guide/language-grammar/possessives/#company-product-and-brand-name-possessives). 24 | -------------------------------------------------------------------------------- /docs/5-formatting/units-of-measurement.md: -------------------------------------------------------------------------------- 1 | # Units of measurement 2 | 3 | [info] **Highlight:** Insert a nonbreaking space between the number and a unit of measurement. [/info] 4 | 5 | ## Spaces in units of measurement 6 | 7 | Insert a nonbreaking space between the number and a unit for most units of measurement. For more information about when to spell out units, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/#spelling-out-and-declaring-abbreviations). 8 | 9 | **Examples** 10 | [warning] **Not recommended:** 16ft [/warning] 11 | [tip] **Recommended:** 16` `ft [/tip] 12 | [tip] **Recommended:** 75` `kg [/tip] 13 | [tip] **Recommended:** 10` `GB [/tip] 14 | 15 | Don't use a space when the unit of measure is a percentage, money, or degrees of an angle. 16 | 17 | **Examples** 18 | [tip] **Recommended:** 55% [/tip] 19 | [tip] **Recommended:** $3000 [/tip] 20 | [tip] **Recommended:** 130° [/tip] 21 | 22 | ## Ranges of numbers with units 23 | 24 | For a range of numbers that have units, repeat the unit for each number in the range. Units include abbreviations (such as *GB* for *Gigabytes*) and symbols (such as the degree symbol (°)), but not nouns like *file*. 25 | 26 | **Examples** 27 | [warning] **Not recommended:** -10-33 °C [/warning] 28 | [tip] **Recommended:** -10 °C to 33 °C [/tip] 29 | [warning] **Not recommended:** The recommended file size is 50 - 100 MB. [/warning] 30 | [tip] **Recommended:** The recommended file size is 50 MB to 100 MB. [/tip] 31 | 32 | For more information, see [En dashes](https://make.wordpress.org/docs/style-guide/punctuation/dashes/#en-dashes), [Ranges of numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/#ranges-of-numbers), and [Numbers and fractions](https://make.wordpress.org/docs/style-guide/punctuation/hyphens/#numbers-and-fractions). 33 | 34 | ## Rates 35 | 36 | Use the word *per* instead of the division slash (/) while indicating rates. It's acceptable to use the division slash where space is too limited. 37 | 38 | Shorten *per* to *p* only for well-established abbreviations such as *Gbps* for *Gigabits per second*. 39 | 40 | **Examples** 41 | [warning] **Not recommended:** The server handles 90k transactions/hour. [/warning] 42 | [tip] **Recommended:** The server handles 90k transactions per hour. [/tip] 43 | 44 | ## Currency 45 | 46 | Mention to the reader distinctly what country's currency that you're referring to. For example, the dollar sign ($) can be mistaken for US dollars, Canadian dollars, Australian dollars, and multiple other currencies. Use [ISO defined country or region codes](https://wikipedia.org/wiki/ISO_4217#Active_codes) to depict international currencies, if possible. 47 | 48 | For more information, see [Currency](https://make.wordpress.org/docs/style-guide/formatting/numbers/#currency). 49 | 50 | ## Using abbreviations to denote numbers 51 | 52 | In general, don't abbreviate *thousand, million*, and *billion* as *K, M*, and *B* or *K, mn* and *bn*. In some contexts, using the abbreviations may be more relevant or suited. If you use abbreviations, see [Abbreviations in numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/#abbreviations) for more information. 53 | -------------------------------------------------------------------------------- /docs/5-formatting/words-as-words.md: -------------------------------------------------------------------------------- 1 | # Words as words 2 | 3 | [info] **Highlight:** Italicize words used as words. [/info] 4 | 5 | While referring to a particular word or phrase as the word or phrase itself, use italic formatting. For additional information about italics, see [Text highlighting](https://make.wordpress.org/docs/style-guide/formatting/text/#text-highlighting). 6 | 7 | **Examples** 8 | [warning] **Not recommended:** Don't substitute a **/** (slash) as a conjunction. Use the word **or** instead. [/warning] 9 | [warning] **Not recommended:** Don't substitute a "/" (slash) as a conjunction. Use the word "or" instead. [/warning] 10 | [warning] **Not recommended:** Don't substitute a / (slash) as a conjunction. Use the word or instead. [/warning] 11 | [tip] **Recommended:** Don't substitute a */* (slash) as a conjunction. Use the word *or* instead. [/tip] 12 | 13 | While referring to letters as letters, use italics. 14 | 15 | **Examples** 16 | [warning] **Not recommended:** If a proper noun ends with an **s**, you can either use an apostrophe and **s** or just an apostrophe. [/warning] 17 | [warning] **Not recommended:** If a proper noun ends with an "s", you can either use an apostrophe and "s" or just an apostrophe. [/warning] 18 | [warning] **Not recommended:** If a proper noun ends with an s, you can either use an apostrophe and s or just an apostrophe. [/warning] 19 | [tip] **Recommended:** If a proper noun ends with an *s*, you can either use an apostrophe and *s* or just an apostrophe. [/tip] 20 | 21 | Use an apostrophe and an *s* to form the plural, but don’t italicize the apostrophe or the *s*. 22 | -------------------------------------------------------------------------------- /docs/6-linking/README.md: -------------------------------------------------------------------------------- 1 | # Linking 2 | 3 | This section provides linking guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/6-linking/cross-references.md: -------------------------------------------------------------------------------- 1 | # Cross-references 2 | 3 | [info] **Highlight:** Use cross-references to guide readers to related information. [/info] 4 | 5 | Cross-references guide the reader to information related to the content. For additional information about internal and external references, see [Link text](https://make.wordpress.org/docs/style-guide/linking/link-text/) and [Capitalization in titles and headings](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/#capitalization-in-titles-and-headings). 6 | 7 | ## References to other documents 8 | 9 | Write relevant and meaningful link text. 10 | 11 | **Examples** 12 | [warning] **Not recommended:** Click [here](https://wordpress.org/news/). [/warning] 13 | [warning] **Not recommended:** See [documentation](https://wordpress.org/support/). [/warning] 14 | [tip] **Recommended:** For the latest release announcements, see [News and Announcements](https://wordpress.org/news/). [/tip] 15 | 16 | If the link text doesn't clearly specify as to why you're referring the reader to related information, then provide explanatory information. Make the explanation specific, but don't repeat the information text. 17 | 18 | **Examples** 19 | [warning] **Not recommended:** For more information, see [WP-CLI Commands](https://developer.wordpress.org/cli/commands/). [/warning] 20 | [tip] **Recommended:** For more information about all the available commands, see [WP-CLI Commands](https://developer.wordpress.org/cli/commands/). [/tip] 21 | 22 | If the link downloads a file, explicitly mention it, and the type of file being downloaded. 23 | 24 | **Example** 25 | [tip] **Recommended:** Get started with the installation process by [downloading the latest WordPress ZIP file](https://wordpress.org/latest.zip). [/tip] 26 | 27 | Don't include multiple links to the same document or article within a page. However, you can add a secondary link, if you're linking to a particular section of the document or if the page you're linking from is long. It is also acceptable to use a secondary link if there are multiple entry points to the document you're linking from. 28 | 29 | ## Cross-references within generated reference documents 30 | 31 | In generated reference documents, while linking from one reference topic to another, use the standard linking syntax rather than hard-coding links within the reference, so that the links will change appropriately when the reference docs change. 32 | 33 | ## Writing cross-references 34 | 35 | While writing descriptions for what the cross-references link to, use *about* instead of *on*. 36 | 37 | **Examples** 38 | [warning] **Not recommended:** For more information on procedural steps that provide instructions to achieve a particular task, see [Procedures and instructions](https://make.wordpress.org/docs/style-guide/formatting/procedures/). [/warning] 39 | [tip] **Recommended:** For more information about procedural steps that provide instructions to achieve a particular task, see [Procedures and instructions](https://make.wordpress.org/docs/style-guide/formatting/procedures/). [/tip] 40 | 41 | ## Formatting cross-references 42 | 43 | - Don't enclose cross-references that are links in quotation marks. 44 | - In case the cross-reference isn't a link, use italics or quotation marks as appropriate. 45 | - Use italics for cross-references that are titles of full-length works such as a movie, book, or paper that are unlinked. 46 | **Example**
47 | [tip] **Recommended:** For more information, see the *American Heritage Dictionary*. [/tip] 48 | - Use quotation marks for cross-references that are short works such as a blog post or a TV episode, and document sections. 49 | **Example**
50 | [tip] **Recommended:** For more information, see "Compound modifiers". [/tip] 51 | 52 | ### Links to sections in the same page 53 | 54 | When you're linking to another section in the same page, mention that the link guides you to a different section on the same page. 55 | 56 | **Example** 57 | [tip] **Recommended:** In this document, see [References to other documents](#). [/tip] 58 | 59 | ### Links to pages on the same server 60 | 61 | When you're linking to another page on the same server, use root-relative URLs starting with `/`, even if you're linking to a page in the same directory as the page you're linking from. 62 | 63 | ### Links to pages on a different domain or server 64 | 65 | - When you're linking to pages on a different domain or server, use absolute URLs. Start the URL with `https` if the server you're linking to supports HTTPS. If the server doesn't support HTTPS, start the URL with `http`. 66 | - Don't force links to open in a new tab or window. Let the reader decide how to open links. If the link needs to open in a new tab or window, notify the reader that the link will open in a new tab or window. 67 | **Example**
68 | [tip] **Recommended:** For more information, see the [American Heritage Dictionary (opens in a new tab)](https://ahdictionary.com/). [/tip] 69 | - Use an external link icon to indicate that the link goes to a different domain or server. Examples of internal links are, a link from *make.wordpress.org* to *developer.wordpress.org* or a link from *wordpress.org/news* to the *make.wordpress.org/docs* subdomain. A link from *developer.wordpress.org* to *github.com/WordPress* is an example of an external link. 70 | **Example**
71 | [tip] **Recommended:** For more information, see the [Gutenberg project repository](https://github.com/WordPress/gutenberg). [/tip] 72 | -------------------------------------------------------------------------------- /docs/6-linking/external-links.md: -------------------------------------------------------------------------------- 1 | # External links 2 | 3 | [info] **Highlight:** It's OK to link to external sites for more information. [/info] 4 | 5 | WordPress documentation is undoubtedly reliant on third-party standards, software, platforms and technologies. Moreover, third-party documentation may become obsolete after upgrades and updates, so there is always the possibility of WordPress documentation potentially referencing obsolete content. Hence, in order to provide abundant references and guidance, it is preferable to link to external sites and sources instead of quoting or rewriting existing documentation. 6 | 7 | Although in some cases, including brief information can save the readers a trip to an external site. 8 | 9 | **Example** 10 | [tip] **Recommended:** To create multiple paragraphs, use the `

` element rather than using the `
` element. For more information on which uses of `
` are correct and which ones aren't, see the [HTML specification for `
`](https://html.spec.whatwg.org/multipage/semantics.html#the-br-element). [/tip] 11 | 12 | Ensure that the sites you link to are of high standard and quality. 13 | 14 | If the URL has a locale indicator, remove it and then test the link. For example, in a Wikipedia link, change the following: 15 | ``` 16 | https://en.wikipedia.org/wiki/XML-RPC 17 | ``` 18 | to this: 19 | ``` 20 | https://wikipedia.org/wiki/XML-RPC 21 | ``` 22 | 23 | Don't force links to open in a new tab or window. Let the reader decide how to open links. If the link needs to open in a new tab or window, notify the reader that the link will open in a new tab or window. 24 | 25 | **Example** 26 | [tip] **Recommended:** For more information, see the [American Heritage Dictionary (opens in a new tab)](https://ahdictionary.com/). [/tip] 27 | 28 | Use an external link icon to indicate that the link goes to a different domain or server. For more information, see [Links to pages on a different domain or server](). 29 | -------------------------------------------------------------------------------- /docs/6-linking/heading-targets.md: -------------------------------------------------------------------------------- 1 | # Headings as link targets 2 | 3 | [info] **Highlight:** Use heading anchors. [/info] 4 | 5 | Heading anchors are useful for document sections that are frequently linked to. To make headings into link targets, add an anchor. To avoid breaking existing heading links in published content, create an anchor that uses the same ID string as the published page. You can also create a custom anchor for a heading; for example, you can create a short anchor for a long heading. A custom anchor decreases the possibility of breaking existing links if the heading text changes. 6 | 7 | ## Adding an anchor 8 | 9 | [info] **Note:** For content published on wordpress.org, WordPress may automatically create a link target for headings by default. For more information about creating heading anchors on WordPress, see [Page jumps](https://wordpress.org/support/article/page-jumps/). [/info] 10 | 11 | {% codetabs %} 12 | {% HTML %} 13 | To add an anchor to a heading in HTML, do the following: 14 | - Add a `

` element with an `id` attribute. Don't use ``. 15 | - Use lowercase for `id` values. 16 | - Insert hyphens between words. 17 | 18 | **Examples** 19 | [warning] **Not recommended:** 20 | ```html 21 |

Determining plugin and content directories

22 | ``` 23 | [/warning] 24 | [warning] **Not recommended:** 25 | ```html 26 | 27 |

Determining plugin and content directories

28 | ``` 29 | [/warning] 30 | [tip] **Acceptable:** 31 | ```html 32 |

Determining plugin and content directories

33 | ``` 34 | [/tip] 35 | [tip] **Recommended:** 36 | ```html 37 |
38 |

Determining plugin and content directories

39 | ... 40 |
41 | ``` 42 | [/tip] 43 | {% Markdown %} 44 | To add an anchor to a heading in Markdown, do the following: 45 | - Add `{:#ID_OF_ANCHOR}` after the heading, to the end of the line that the heading is on. Replace ID_OF_ANCHOR with the ID for this heading. 46 | - Use lowercase for `id` values. 47 | - Insert hyphens between words. 48 | 49 | **Examples** 50 | [warning] **Not recommended:** 51 | ```markdown 52 | ## Determining plugin and content directories {: id="ID_OF_ANCHOR" } 53 | ``` 54 | [/warning] 55 | [warning] **Not recommended:** (Note single quotation marks) 56 | ```markdown 57 | ## Determining plugin and content directories {: id='ID_OF_ANCHOR' } 58 | ``` 59 | [/warning] 60 | [warning] **Not recommended:** 61 | ```markdown 62 | ## Determining plugin and content directories 63 | {:#ID_OF_ANCHOR} 64 | ``` 65 | [/warning] 66 | [tip] **Acceptable:** 67 | ```markdown 68 | ## Determining plugin and content directories {: id="determining-directories" } 69 | ``` 70 | [/tip] 71 | [tip] **Recommended:** 72 | ```markdown 73 | ## Determining plugin and content directories {:#determining-plugin-and-content-directories} 74 | ``` 75 | [/tip] 76 | [tip] **Recommended:** 77 | ```markdown 78 | ## Determining plugin and content directories {:#determining-plugin-content-directories} 79 | ``` 80 | [/tip] 81 | {% end %} 82 | 83 | ## Changing an anchor 84 | 85 | [info] **Note:** For content published on wordpress.org, WordPress may automatically create a link target for headings by default. For more information about creating heading anchors on WordPress, see [Page jumps](https://wordpress.org/support/article/page-jumps/). [/info] 86 | 87 | To change an anchor, you need to create a custom anchor that uses the older ID string. A custom anchor decreases the possibility of breaking existing links if the heading text changes. You can find the ID string by inspecting the heading. 88 | 89 | {% codetabs %} 90 | {% HTML %} 91 | 92 | If you change a heading from *Custom template files* to *Custom post type template files*, then add a custom anchor that uses the older ID string and formatting. 93 | 94 | **Example** 95 | [tip] **Recommended:** 96 | ```html 97 |
98 |

Custom post type template files

99 | ... 100 |
101 | ``` 102 | [/tip] 103 | {% Markdown %} 104 | 105 | If you change a heading from *Custom template files* to *Custom post type template files*, then add a custom anchor that uses the older ID string and formatting. 106 | 107 | **Example** 108 | [tip] **Recommended:** 109 | ```markdown 110 | ## Custom post type template files {:#custom_template_files} 111 | ``` 112 | [/tip] 113 | {% end %} 114 | -------------------------------------------------------------------------------- /docs/6-linking/image-links.md: -------------------------------------------------------------------------------- 1 | # Image links 2 | 3 | [info] **Highlight:** Use root-relative URLs for image links. [/info] 4 | 5 | When you're including an image that is served from the same domain as your document or page, use a root-relative URL starting with `/`. Use this root-relative URL format (starting from the site root), even if you're linking to a page in the same directory as the page you're linking from. 6 | 7 | {% codetabs %} 8 | {% HTML %} 9 | Insert the URL in the `src` attribute of the `` element: 10 | ```html 11 | The WordPress mascot Wapuu. 15 | ``` 16 | {% Markdown %} 17 | Insert the URL in parentheses after the image's alt text: 18 | ```markdown 19 | ![The WordPress mascot Wapuu.](/assets/images/wapuu.png) 20 | ``` 21 | {% end %} 22 | -------------------------------------------------------------------------------- /docs/6-linking/link-text.md: -------------------------------------------------------------------------------- 1 | # Link text 2 | 3 | [info] **Highlight:** Write detailed and expressive link text that provides context. [/info] 4 | 5 | Write detailed and expressive link text that describes where the reader will be guided to, and what the reader will see after following the link. Links, by themselves, should be coherent without the surrounding text. 6 | Links can be of two forms: 7 | - The exact text of the title, heading, or subheading you're linking to. For more information about capitalizing such references, see [Capitalization in references to titles and headings](https://make.wordpress.org/docs/style-guide/language-grammar/capitalization/#capitalization-in-references-to-titles-and-headings). 8 | - A description of the linked document or page, with standard text capitalization. 9 | 10 | For more information about link text, see [Cross-references](https://make.wordpress.org/docs/style-guide/linking/cross-references/). 11 | 12 | ## General guidelines for link text 13 | 14 | - You can rewrite or rephrase a sentence to include a phrase to get well-articulated and clear link text. 15 | - Don't use a URL as link text. Instead, use the page title or a description of the page. 16 | - Don't use the phrase *click here* or *this document*. It impedes scannability and accessibility. 17 | - Don't force links to open in a new tab or window. Let the reader decide how to open links. If the link needs to open in a new tab or window, notify the reader that the link will open in a new tab or window. For more information, see [Links to pages on a different domain or server](https://make.wordpress.org/docs/style-guide/linking/cross-references/#links-to-pages-on-a-different-domain-or-server). 18 | - Use an external link icon to indicate that the link goes to a different domain or server. For more information, see [Links to pages on a different domain or server](https://make.wordpress.org/docs/style-guide/linking/cross-references/#links-to-pages-on-a-different-domain-or-server). 19 | - If the link downloads a file, explicitly mention it, and the type of file being downloaded. 20 | - If you're referencing a link with an abbreviation, include both the spelled-out term or phrase and the abbreviation in the link text. For example, link to [WordPress Command Line Interface (WP-CLI)](https://make.wordpress.org/cli/), not [WordPress Command Line Interface](https://make.wordpress.org/cli/) (WP-CLI). 21 | 22 | **Examples** 23 | [warning] **Not Recommended (HTML):** Click `here`. [/warning] 24 | [warning] **Not Recommended (HTML):** Want more? Go to `this page!`. [/warning] 25 | [tip] **Recommended (HTML):** For more information, see `Word choice`. [/tip] 26 | [warning] **Not Recommended (Markdown):** Click `[here]()`. [/warning] 27 | [warning] **Not Recommended (Markdown):** Want more? Go to `[this page!]()`. [/warning] 28 | [tip] **Recommended (Markdown):** For more information, see `[Word choice]()`. [/tip] 29 | [warning] **Not Recommended (HTML):** See trademark policy at `https://wordpressfoundation.org/trademark-policy/`. [/warning] 30 | [tip] **Recommended (HTML):** For more information about WordPress trademarks, see the `Trademark Policy for WordPress`. [/tip] 31 | [warning] **Not Recommended (Markdown):** See trademark policy at `[https://wordpressfoundation.org/trademark-policy/](https://wordpressfoundation.org/trademark-policy/)`. [/warning] 32 | [tip] **Recommended (Markdown):** For additional information about WordPress trademarks, see the `[Trademark Policy for WordPress](https://wordpressfoundation.org/trademark-policy/)`. [/tip] 33 | 34 | ## Punctuation with links 35 | 36 | If you have punctuation immediately before or after a link, insert the punctuation outside the link tags where possible. For example, don't include sentence ending punctuation such as a period inside link text. 37 | 38 | **Examples** 39 | [warning] **Not Recommended (HTML):** For the latest release announcements, see `News and Announcements.` [/warning] 40 | [tip] **Recommended (HTML):** For the latest release announcements, see `News and Announcements`. [/tip] 41 | [warning] **Not Recommended (Markdown):** For the latest release announcements, see `[News and Announcements.](https://wordpress.org/news/)` [/warning] 42 | [tip] **Recommended (Markdown):** For the latest release announcements, see `[News and Announcements](https://wordpress.org/news/)`. [/tip] 43 | -------------------------------------------------------------------------------- /docs/7-developer-content/README.md: -------------------------------------------------------------------------------- 1 | # Developer content 2 | 3 | This section provides developer content guidelines for writing WordPress documentation. 4 | -------------------------------------------------------------------------------- /docs/7-developer-content/code-examples.md: -------------------------------------------------------------------------------- 1 | # Code examples 2 | 3 | [info] **Highlight:** Use code blocks, preformatted text, and code fences to write code examples. [/info] 4 | 5 | In documentation, mark a block of code such as a lengthy command or a code example to distinguish it from standard text. To express code examples in HTML, use the `
` element. In Markdown, use a code fence (` ``` `).
 6 | 
 7 | This page explains how to format code examples in documentation. For more information about other code-related documentation, see [Code in text](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/), [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/), and [Command-line syntax](https://make.wordpress.org/docs/style-guide/developer-content/command-line-syntax/).
 8 | 
 9 | For more information about adding code blocks in the Gutenberg block editor, see [Code block](https://wordpress.org/support/article/code-block/) and [Preformatted block](https://wordpress.org/support/article/preformatted-block/).
10 | 
11 | ## General guidelines for code examples
12 | 
13 | - Use spaces to indent code. Don't use tabs unless specified.
14 | - Follow the indentation standards in the relevant [coding standards guide](https://make.wordpress.org/docs/style-guide/developer-content/coding-standards/).
15 | - Wrap lines after 80 characters.
16 | - Mark code blocks as preformatted text. In HTML, use a `
` element; in Markdown, indent every line of the code block by four spaces.
17 | 
18 | For more information see [Coding standards](https://make.wordpress.org/docs/style-guide/developer-content/coding-standards/).
19 | 
20 | **Example**  
21 | [tip] **Recommended:**  
22 | ```html
23 | 
24 | function longSentence() {
25 |   alert('This example of a sentence is very long and wraps onto a second
26 |     line.');
27 | }
28 | 

29 | ```  
30 | This preformatted code example renders a code block with syntax highlighting as follows:  
31 | 
32 | ```js
33 | function longSentence() {
34 |   alert('This example of a sentence is very long and wraps onto a second
35 |     line.');
36 | }
37 | ```  
38 | [/tip]  
39 | 
40 | ## Introductory sentences
41 | 
42 | In most cases, introduce a code example with an introductory sentence that initiates the example that follows. If the heading of the content explains what the code example is about, and no additional context is required, then don't include an introductory statement. You can introduce a code example with an imperative statement.
43 | 
44 | 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 code example. The text preceding the colon must distinctly stand alone as a complete sentence. That is, don't introduce a code example with a partial statement.
45 | 
46 | **Examples**  
47 | [warning] **Not recommended (ending with a colon):** The following code example shows how to use the `post` method. For information on other methods, refer the [Code reference](https://developer.wordpress.org/reference/methods/): [Code example] [/warning]  
48 | [tip] **Recommended (ending with a period):** The following code example shows how to use the `post` method. For information on other methods, refer the [Code reference](https://developer.wordpress.org/reference/methods/). [Code example] [/tip]  
49 | [tip] **Recommended:** The following code example shows how to use the `post` method: [Code example] For information on other methods, see the [Code reference](https://developer.wordpress.org/reference/methods/). [/tip]  
50 | 


--------------------------------------------------------------------------------
/docs/7-developer-content/code-in-text.md:
--------------------------------------------------------------------------------
 1 | # Code in text
 2 | 
 3 | [info] **Highlight:** Insert code-related content in monospace code font. [/info]  
 4 | 
 5 | In text content, use monospace code font to highlight and distinguish code content from standard text. To express code font in HTML, use the `` element. In Markdown, use backticks (``` ` ```) for code font.
 6 | 
 7 | This page explains how to format code in standard text sentences. For more information about other code-related documentation, see [Code examples](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/), [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/), and [Command-line syntax](https://make.wordpress.org/docs/style-guide/developer-content/command-line-syntax/).
 8 | 
 9 | ## Items to put in code font
10 | 
11 | Use monospace code font while expressing the following items, which include but are not limited to:
12 | - Attribute names and values.
13 | - Class names.
14 | - Command-line utility names.
15 | - Data types.
16 | - Defined (constant) values for an element or attribute.
17 | - [DNS record types](https://wikipedia.org/wiki/List_of_DNS_record_types).
18 | - Enum (enumerator) names.
19 | - Environment variable names.
20 | - Element names in XML and HTML. Place angle brackets (`<>`) around the element name; you may have to escape the angle brackets to make them appear in the document.
21 | - [Filenames](https://make.wordpress.org/docs/style-guide/formatting/filenames/), [filename extensions](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types), and paths.
22 | - Folders and directories.
23 | - HTTP verbs, status codes, and content-type values.
24 | - Language keywords.
25 | - Method and function names.
26 | - Namespace aliases.
27 | - [Placeholder variables](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/#placeholder-variables).
28 | - Query parameter names and values.
29 | - Text input.
30 | - [UI elements](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/) that implement previously entered text input. For example, if the user was instructed to enter a name for a UI element as `post-name`, then when you tell them to click the element, use code font and bold: *Click __`post-name`__*.
31 | 
32 | For more information, see [Code text preceding colon](https://make.wordpress.org/docs/style-guide/punctuation/colons/#code-text-preceding-colon).
33 | 
34 | ## Items to put in regular (non-code) font
35 | 
36 | Use standard font while expressing the following items, which include but are not limited to:
37 | - Email addresses.
38 | - Names of products, services, and organizations. However, when a product name is also a command-line utility name, code font can be used.
39 | - URLs. For more information, see [Link text](https://make.wordpress.org/docs/style-guide/linking/link-text/).
40 | 
41 | ## Method names
42 | 
43 | When you refer to a method name in text, omit the class name except where including it would prevent ambiguity. Insert empty parentheses at the end of the method name to indicate that it's a method.
44 | 
45 | **Examples**  
46 | [warning] **Not recommended:** To delete a file or directory, call the `WP_Filesystem_ftpsockets::delete()` method. [/warning]  
47 | [tip] **Recommended:** To delete a file or directory, call the `delete()` method. [/tip]  
48 | 
49 | ## Commands
50 | 
51 | To mark a block of code such as a lengthy command or a code example, use the following formatting:
52 | - In HTML, use the `
` element.
53 | - In Markdown, use a code fence (` ``` `).
54 | 
55 | Formatting a command with multiple elements:
56 | - When a line exceeds 100 characters, you can safely add a line break before some characters, such as a single hyphen, double hyphen, underscore, or quotation marks. After the first line, indent each line by four spaces to vertically align each line that follows a line break.
57 | - If you split a command line with a line break, each line except the last line must end with the command-continuation character. Commands that don't have the command-continuation character don't work. Command-continuation characters are:
58 |   - Linux or shell: A backslash preceded with a space (` \`)
59 |   - Windows: A caret preceded with a space (` ^`)
60 | - Use placeholder text with [placeholder variables](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/#placeholder-variables).
61 | - Write a descriptive list of the placeholder variables used in the command line succeeding the command line. For more information, see [Describing placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/#describing-placeholders).
62 | 
63 | ## Keywords
64 | 
65 | Avoid using technical keywords as verbs or nouns. If you have to, don't change the word form of the keywords; don't make plurals from keywords, change tense, or convert them to possessive form. It's acceptable to use lowercase, plain text *string* in a general discussion of the `STRING` data type.
66 | 
67 | **Examples**  
68 | [warning] **Not recommended:** `Decompress` the encoded body. [/warning]  
69 | [tip] **Recommended:** Decompress the encoded body by using a `decompress` request. [/tip]  
70 | [warning] **Not recommended:** Retrieve information by `get`ting the data. [/warning]  
71 | [tip] **Recommended:** To retrieve the data, send a `get` request. [/tip]  
72 | [warning] **Not recommended:** Before `patch()`ing, make sure your request is `post()`ed. [/warning]  
73 | [tip] **Recommended:** Send a `post()` request before calling a `patch()` request. [/tip]  
74 | 
75 | ## HTTP status codes
76 | 
77 | Use the following formatting and phrasing to refer to a single HTTP status code: an HTTP `500 Internal server error` status code.
78 | 
79 | Insert the HTTP status code number and name in code font. Specifically use *status code* rather than *error code* or *response code*. If *HTTP* is implied from context, it is acceptable to exclude it.
80 | 
81 | Use the following formatting to refer a range of HTTP status codes: an HTTP `2xx` or `300` status code.
82 | 
83 | Insert the HTTP status code number in code font even if you're excluding the code name. Use *Nxx* where N is a digit, to indicate *anything in the N00 to N99 range*.
84 | 
85 | Use the following formatting to specify an exact range of HTTP status codes: an HTTP status code in the `200`-`299` range.
86 | 
87 | Insert the HTTP status code number in code font.
88 | 
89 | ## Coding standards
90 | 
91 | For more information about coding standards for WordPress, see [Coding standards](https://make.wordpress.org/docs/style-guide/developer-content/coding-standards/).
92 | 


--------------------------------------------------------------------------------
/docs/7-developer-content/coding-standards.md:
--------------------------------------------------------------------------------
 1 | # Coding standards
 2 | 
 3 | [info] **Highlight:** Follow WordPress coding standards. [/info]  
 4 | 
 5 | WordPress is a global project with thousands of contributors. It’s important that the best practices are followed so that the codebase is consistent and readable, and changes are easy to find and read, whether the code is five days old or five years old. WordPress coding standards are a series of best practices to help keep WordPress code clean and well documented.
 6 | 
 7 | The purpose of WordPress coding standards is to create a baseline for collaboration and review within various aspects of the WordPress open source project and community, from core code to themes to plugins.
 8 | 
 9 | The coding standard guides for WordPress are available in the [WordPress coding standards handbook](https://developer.wordpress.org/coding-standards/):
10 | - [Accessibility coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/)
11 | - [CSS coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/)
12 | - [HTML coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/)
13 | - [JavaScript coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/)
14 | - [PHP coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
15 | - [Inline documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation-standards/)
16 |   - [PHP documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/)
17 |   - [JavaScript documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/)
18 | - [Markdown style guide](https://developer.wordpress.org/coding-standards/styleguide/)
19 | 


--------------------------------------------------------------------------------
/docs/7-developer-content/command-line-syntax.md:
--------------------------------------------------------------------------------
  1 | # Command-line syntax
  2 | 
  3 | [info] **Highlight:** Follow proper command-line syntax and formatting. [/info]  
  4 | 
  5 | This page explains how to format commands and their arguments in documentation. For more information about other code-related documentation, see [Code in text](https://make.wordpress.org/docs/style-guide/developer-content/code-in-text/), [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/), and [Code examples](https://make.wordpress.org/docs/style-guide/developer-content/code-examples/).
  6 | 
  7 | ## Command prompt
  8 | 
  9 | When you have to show multiple lines of command-line input, initiate each line with the dollar (`$`) command prompt symbol.
 10 | 
 11 | Don't show the current directory path before the prompt, even if part of the instruction includes creating or changing directories. This is because the directory structure might be different for the user. However, if the general context of the command-line interface changes—such as from the local machine to a remote machine—then add an additional prompt indicator for the new context.
 12 | 
 13 | **Examples**  
 14 | [tip] **Recommended:**  
 15 | ```shell
 16 | $ wp theme activate twentytwentyone
 17 | ```  
 18 | The output is the following:  
 19 | 
 20 | ```
 21 | Success: Switched to 'Twenty Twenty-One' theme.
 22 | ```  
 23 | [/tip]  
 24 | [tip] **Recommended:**  
 25 | ```shell
 26 | $ pwd
 27 | /srv/www/wordpress-develop.dev
 28 | $ cat wp-cli.yml
 29 | path: src/
 30 | ```  
 31 | [/tip]  
 32 | 
 33 | For single-line commands, the command prompt, that is the dollar symbol (`$`) is optional. However, if you have to show both multi-line and single-line commands, use the command prompt symbol for overall consistency.
 34 | 
 35 | Use separate code blocks for command-line instructions that include both input and output lines.
 36 | 
 37 | **Example**  
 38 | [tip] **Recommended:**  
 39 | ```shell
 40 | $ wp cap list 'editor' | xargs wp cap add 'author'
 41 | ```  
 42 | The output is the following:  
 43 | 
 44 | ```
 45 | Success: Added 24 capabilities to 'author' role.
 46 | ```  
 47 | [/tip]  
 48 | 
 49 | ## Required commands and arguments
 50 | 
 51 | When writing commands and arguments that are required, use code font without brackets, braces, or parentheses.
 52 | 
 53 | **Examples**  
 54 | [tip] **Recommended:**  
 55 | ```shell
 56 | $ wp post list --post_type='page' --format=ids
 57 | ```  
 58 | [/tip]  
 59 | [tip] **Recommended:**  
 60 | ```shell
 61 | $ wp core check-update
 62 | ```  
 63 | [/tip]  
 64 | In these examples, all words and arguments are required.  
 65 | 
 66 | For more information, see [Anatomy of a command](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/#anatomy-of-a-command).
 67 | 
 68 | ## Optional arguments
 69 | 
 70 | When writing arguments that are optional, enclose the arguments in square brackets. If there is more than one optional argument, enclose each item in its individual set of square brackets.
 71 | 
 72 | **Example**  
 73 | [tip] **Recommended:**  
 74 | ```shell
 75 | $ wp plugin install https://wordpress.org/plugins/gutenberg/ [--force] [--activate]
 76 | ```  
 77 | [/tip]  
 78 | In this example, `install` is required, but `[--force]` and `[--activate]` are optional arguments.
 79 | 
 80 | ## Mutually exclusive arguments
 81 | 
 82 | When writing commands where the use has to choose one item, enclose the items in angle brackets (`<>`; also known as *inequality signs*). Sometimes the mutually exclusive choices are also enclosed in braces (also known as *curly braces*). Use vertical bars (also knows as *pipes*) to separate the items. You can have more than two mutually exclusive items that are separated from each other by pipes.
 83 | 
 84 | **Example**  
 85 | [tip] **Recommended:**  
 86 | ```shell
 87 | $ wp plugin install 
 88 | ```  
 89 | [/tip]  
 90 | In this example, `install` is required, and `` is the accepted positional argument. In fact, `wp plugin install` accepts the same positional argument (the slug, ZIP, or URL of a plugin to install). The `plugin`, `zip`, and `url` choices are mutually exclusive, but one of the argument must be specified.
 91 | 
 92 | ## Multiple value arguments
 93 | 
 94 | Use an ellipsis (`...`) to indicate that the user can specify multiple values for the argument.
 95 | 
 96 | **Examples**  
 97 | [tip] **Recommended:**  
 98 | ```shell
 99 | $ wp media import [--post_id=...]
100 | ```  
101 | [/tip]  
102 | In this example, the ellipsis indicates that the user can specify multiple instances of the optional argument `[--post_id=]`.
103 | [tip] **Recommended:**  
104 | ```shell
105 | $ wp plugin install ...
106 | ```  
107 | [/tip]  
108 | In this example, the ellipsis indicates that the user can specify multiple plugins, zip files or URLs.
109 | 
110 | ## Command output
111 | 
112 | You don't have to show an output for every command. Only add the output if it is useful; for example, if the user needs to copy a value or needs to verify a value from the output.
113 | 
114 | If you do show have to show an output, use an introductory phrase to separate the command from the output.
115 | 
116 | **Examples**  
117 | [tip] **Recommended:**  
118 | ```shell
119 | $ wp theme status twentytwentyone
120 | ```  
121 | The output is the following:
122 | 
123 | ```
124 | Theme twentytwentyone details:
125 |      Name: Twenty Twenty-One
126 |      Status: Active
127 |      Version: 1.1
128 |      Author: WordPress.org
129 | ```  
130 | [/tip]  
131 | [tip] **Recommended:**  
132 | ```shell
133 | $ wp server --host=localhost.localdomain --port=80
134 | ```  
135 | The output is similar to the following:
136 | 
137 | ```
138 | PHP 5.6.9 Development Server started at Fri Jan 22 11:32:56 2021
139 | Listening on http://localhost1.localdomain1:80
140 | Document root is /
141 | Press Ctrl-C to quit.
142 | ```  
143 | [/tip]  
144 | 
145 | For more information about explaining placeholders in output, see [Placeholders in output](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/#placeholders-in-output).
146 | 
147 | ## Additional resources
148 | 
149 | - [WP-CLI Handbook](https://make.wordpress.org/cli/handbook/)
150 | - [WP-CLI Commands](https://developer.wordpress.org/cli/commands/)
151 | 


--------------------------------------------------------------------------------
/docs/8-word-list/README.md:
--------------------------------------------------------------------------------
1 | # Word list and usage dictionary
2 | 
3 | [info] **Highlight:** Refer the word list for spellings and word usage guidelines for specific words. [/info]  
4 | 
5 | This section provides word usage guidelines for writing WordPress documentation.
6 | 


--------------------------------------------------------------------------------
/docs/8-word-list/j.md:
--------------------------------------------------------------------------------
 1 | # J
 2 | 
 3 | ## Java
 4 | 
 5 | Capitalize.
 6 | 
 7 | Don't use a filename extension to refer to a type of file. For example, use *Java file* rather than *.java file*.
 8 | 
 9 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
10 | 
11 | ## JavaScript
12 | 
13 | One word. Not *Java Script* or *Java-Script*. Capitalize *J* and *S* in *JavaScript*.
14 | 
15 | Don't use a filename extension to refer to a type of file. For example, use *JavaScript file* rather than *.js file*.
16 | 
17 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
18 | 
19 | ## JPEG
20 | 
21 | Acronym for *Joint Photographic Experts Group*. Use uppercase.
22 | 
23 | Don't use a filename extension to refer to a type of file. For example, use *JPEG file* or *JPG file* rather than *.jpeg file* or *jpg file*.
24 | 
25 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
26 | 
27 | ## JSON
28 | 
29 | Acronym for *JavaScript Object Notation*. Use uppercase.
30 | 
31 | Don't use a filename extension to refer to a type of file. For example, use *JSON file* rather than *.json file*.
32 | 
33 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
34 | 
35 | ## jump
36 | 
37 | Don't use as a noun to refer to cross-references to other pages or to links.
38 | 
39 | Don't use as a verb to refer to going from one link to another. Use go to instead.
40 | 
41 | For more information, see [Interaction verbs](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#interaction-verbs).
42 | 
43 | ## just
44 | 
45 | Avoid using. In most cases, *just* is a filler word that can be omitted without changing the meaning of a sentence.
46 | 
47 | **Examples**  
48 | [warning] **Not recommended:** The `wp_mail()` function just sends an email. [/warning]  
49 | [tip] **Recommended:** The `wp_mail()` function sends an email. [/tip]  
50 | 
51 | If your meaning is unclear without *just*, then use a more specific term such as *only, instead,* or *previously*, or rephrase or rewrite your language to be more specific.
52 | 
53 | **Examples**  
54 | [warning] **Not recommended:** Drag the block just as you would drag to upload an image. [/warning]  
55 | [tip] **Recommended:** Drag the block in the same way that you would drag to upload an image. [/tip]  
56 | [warning] **Not recommended:** Just the Network Admin has the ability to install themes, plugins, and edit user profiles in a WordPress multisite network. [/warning]  
57 | [tip] **Recommended:** Only the Network Admin has the ability to install themes, plugins, and edit user profiles in a WordPress multisite network. [/tip]  
58 | [tip] **Recommended:** The Network Admin has the ability to install themes, plugins, and edit user profiles in a WordPress multisite network. [/tip]  
59 | 
60 | It is acceptable to use *just* to describe an approach that is easier or simpler than another.
61 | 
62 | **Example**  
63 | [tip] **Recommended:** To add a new block, click on the **Inserter** button, or just use the slash command. [/tip]  
64 | 
65 | ## justify, justified
66 | 
67 | Don't use to refer to the alignment of text to the left or right margin. Instead, use *alignment*. Justified text is text that is aligned on both the right and the left margins. To describe alignment on one margin only, use *left-aligned* or *right-aligned*, not *left-justified* or *right-justified*.
68 | 
69 | See also [alignment](https://make.wordpress.org/docs/style-guide/word-list/a/#alignment), [left align, left-aligned](https://make.wordpress.org/docs/style-guide/word-list/l/#left-align-left-aligned), [right align, right-aligned](https://make.wordpress.org/docs/style-guide/word-list/r/#right-align-right-aligned).
70 | 


--------------------------------------------------------------------------------
/docs/8-word-list/k.md:
--------------------------------------------------------------------------------
  1 | # K
  2 | 
  3 | ## kB, KB, kilobyte
  4 | 
  5 | Initialism for *kilobyte*.
  6 | 
  7 | In the decimal system, *kilobyte* is abbreviated as *kB*, where one *kB* equals 1000 bytes in the context of file size or storage capacity.
  8 | In the binary system, *kilobyte* is abbreviated as *KB*, where one *KB* equals 1024 bytes in the context of computer memory.
  9 | 
 10 | In the noun form, insert a space between the numeral and the abbreviation. Use the preposition *of* before the unit.
 11 | 
 12 | **Example**  
 13 | [tip] **Recommended:** 1000 KB of memory [/tip]  
 14 | 
 15 | Don’t hyphenate the adjective form.
 16 | 
 17 | **Example**  
 18 | [tip] **Recommended:** a 2 KB file [/tip]  
 19 | 
 20 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 21 | 
 22 | ## kbit, Kbit, kilobit
 23 | 
 24 | Initialism for *kilobit*.
 25 | 
 26 | In the decimal system, *kilobit* is abbreviated as *kbit*, where one *kbit* equals 1000 bits in the context of file size or storage capacity.
 27 | In the binary system, *kilobit* is abbreviated as *Kbit*, where one *Kbit* equals 1024 bits in the context of computer memory.
 28 | 
 29 | In the noun form, insert a space between the numeral and the abbreviation. Use the preposition *of* before the unit.
 30 | 
 31 | **Example**  
 32 | [tip] **Recommended:** 128 KBit of memory [/tip]  
 33 | 
 34 | Don’t hyphenate the adjective form.
 35 | 
 36 | **Example**  
 37 | [tip] **Recommended:** a 256 KBit file [/tip]  
 38 | 
 39 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 40 | 
 41 | ## kbps (kbit/s), Kbps (Kbit/s), kilobits per second
 42 | 
 43 | Initialism for *kilobits per second*.
 44 | 
 45 | For more information, see [Units of measurement](https://make.wordpress.org/docs/style-guide/formatting/units-of-measurement/).
 46 | 
 47 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 48 | 
 49 | See also [kbit, Kbit, kilobit](#kbit-kbit-kilobit).
 50 | 
 51 | ## kBps (kB/s), KBps (KB/s), kilobytes per second
 52 | 
 53 | Initialism for *kilobytes per second*.
 54 | 
 55 | For more information, see [Units of measurement](https://make.wordpress.org/docs/style-guide/formatting/units-of-measurement/).
 56 | 
 57 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 58 | 
 59 | See also [kB, KB, kilobyte](#kB-kb-kilobyte).
 60 | 
 61 | ## key
 62 | 
 63 | Don't use as a verb. Use *type* or *press*. In the adjective form, don't use as a synonym for *crucial* or *important*.
 64 | 
 65 | When using *key* as a noun, specify which kind of key you're referring to on first mention, because there are many kinds of keys in technical contexts.
 66 | 
 67 | For more information, see [Interaction verbs](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#enter-type-input) and [Pressing and typing keyboard keys](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#pressing-and-typing-keyboard-keys).
 68 | 
 69 | ## keyboard shortcut
 70 | 
 71 | Use to describe a combination of keystrokes used to perform a task.
 72 | 
 73 | ## keypress
 74 | 
 75 | One word. Not *key press* or *key-press*.
 76 | 
 77 | ## key ring
 78 | 
 79 | Two words. Not *keyring* or *key-ring*.
 80 | 
 81 | ## keystroke
 82 | 
 83 | One word. Not *key stroke* or *key-stroke*.
 84 | 
 85 | ## key-value pair
 86 | 
 87 | Hyphenate. Not *key value* or *key/value pair*.
 88 | 
 89 | ## kHz, kilohertz
 90 | 
 91 | Initialism for *kilohertz*.
 92 | 
 93 | In the noun form, insert a space between the numeral and the abbreviation. Use the preposition *of* before the unit.
 94 | 
 95 | **Example**  
 96 | [tip] **Recommended:** a rate of 96 kHz [/tip]  
 97 | 
 98 | Don’t hyphenate the adjective form.
 99 | 
100 | **Example**  
101 | [tip] **Recommended:** a 96 kHz rate [/tip]  
102 | 
103 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
104 | 
105 | ## kill
106 | 
107 | Avoid when possible. Instead, use words like *stop, exit, cancel*, or *end*.
108 | 
109 | OK to use in UNIX-related documentation.
110 | 


--------------------------------------------------------------------------------
/docs/8-word-list/n.md:
--------------------------------------------------------------------------------
  1 | # N
  2 | 
  3 | ## n
  4 | 
  5 | Use lowercase and use italic formatting when using as a variable or placeholder.
  6 | 
  7 | For more information, see [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/).
  8 | 
  9 | ## N/A
 10 | 
 11 | Abbreviation for *not available* or *not applicable*. Spell out on first reference.
 12 | 
 13 | Not *NA, N-A,* or *na*.
 14 | 
 15 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 16 | 
 17 | ## name server
 18 | 
 19 | Two words. Not *nameserver* or *name-server*.
 20 | 
 21 | ## namespace
 22 | 
 23 | One word. Not *name space* or *name-space*.
 24 | 
 25 | ## native
 26 | 
 27 | Avoid using. Instead, use a more accurate term such as *core* or *built-in* whenever possible.
 28 | 
 29 | For more information, see [Replacing established terms](https://make.wordpress.org/docs/style-guide/general-guidelines/inclusivity/#replacing-established-terms).
 30 | 
 31 | ## navigate
 32 | 
 33 | Avoid using to describe going from one place to other on the internet or other networks. Instead, use *browse*.
 34 | 
 35 | To describe going directly to a website or webpage, whether by entering a URL or selecting a link, use *go to*.
 36 | 
 37 | Avoid using *navigate* for interacting with UI elements.
 38 | 
 39 | For more information, see [Interaction verbs](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#interaction-verbs).
 40 | 
 41 | See also [go to](https://make.wordpress.org/docs/style-guide/word-list/g/#go-to).
 42 | 
 43 | ## need
 44 | 
 45 | Use *need* to refer to a requirement or obligation. Don't use *desire* or *wish* as a synonym for *need*.
 46 | 
 47 | Use *want* when the user has a choice of actions or when they are optional.
 48 | 
 49 | See also [want](https://make.wordpress.org/docs/style-guide/word-list/w/#want).
 50 | 
 51 | ## neither
 52 | 
 53 | Write *neither A nor B*, not *neither A or B*.
 54 | 
 55 | ## network
 56 | 
 57 | Don't abbreviate to *net*. Don't use *network* as a verb to refer to the action of connecting a computer to a network.
 58 | 
 59 | Computers are *on*, not *in*, a network; and computers on a network are *linked* or *connected*, not *networked*.
 60 | 
 61 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 62 | 
 63 | ## new
 64 | 
 65 | In most cases, avoid describing a product or feature as *new* as it is likely to become out of date. Instead, state the version of software in which the feature or product was introduced.
 66 | 
 67 | ## newer
 68 | 
 69 | Don't use as a synonym for *later* to refer to subsequent versions of a product or software. Instead, use *later*.
 70 | 
 71 | See also [earlier](https://make.wordpress.org/docs/style-guide/word-list/e/#earlier), [later](https://make.wordpress.org/docs/style-guide/word-list/l/#later).
 72 | 
 73 | ## NGINX
 74 | 
 75 | Acronym for *engine X*. Use uppercase.
 76 | 
 77 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
 78 | 
 79 | ## non-
 80 | 
 81 | In general, don't hyphenate words beginning with *non-* such as *nonstandard, noncompliant,* and *nonrestrictive*, unless *non-* is followed by a proper noun or it is absolutely necessary to avoid confusion.
 82 | 
 83 | Don't use *non-* to negate an entire phrase.
 84 | 
 85 | **Examples**  
 86 | [warning] **Not recommended:** non-numbered steps or instructions [/warning]  
 87 | [tip] **Recommended:** steps or instructions that are not numbered [/tip]  
 88 | 
 89 | For more information, see [Hyphens](https://make.wordpress.org/docs/style-guide/punctuation/hyphens/).
 90 | 
 91 | For word usage of specific terms, see [The American Heritage Dictionary](https://ahdictionary.com/).
 92 | 
 93 | ## nonprintable, nonprinting
 94 | 
 95 | Use *nonprintable* to refer to an area of a page that can't be printed on. Use *nonprinting* to refer to characters and other data that can't or won't be printed.
 96 | 
 97 | Don't use *unprintable*.
 98 | 
 99 | ## normal, normally
100 | 
101 | Don't use *normal* to as a synonym for *usual, typical, common*, or a similar term. Don't use *normally* as a synonym for *usually, typically, commonly, often, generally,* or a similar term.
102 | 
103 | ## notification
104 | 
105 | Use instead of *notice* to describe information displayed to a user such as errors, updates, or other communications. Don't use *pop-up, toast*, or *banner*.
106 | 
107 | For more information about notice types in WordPress, see [Notices](https://make.wordpress.org/docs/style-guide/formatting/notices/).
108 | 
109 | ## number
110 | 
111 | OK to abbreviate as *no.* in UI, tables, or headings where space is limited. It's acceptable to abbreviate *number* as *no.*, but consider a global audience; as many languages don't abbreviate *number* as *no.* which may cause confusion.
112 | 
113 | For more information about formatting numbers, see [Numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/).
114 | 
115 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
116 | 
117 | See also [# (number sign)](https://make.wordpress.org/docs/style-guide/word-list/symbols/#number-sign).
118 | 
119 | ## null
120 | 
121 | Use lowercase *null* to refer to a null value. Whenever possible, use *null value* to avoid confusion with the constant.
122 | 
123 | Use uppercase *NULL* or capitalized *Null* only to refer to the constant.
124 | 
125 | ## numeric
126 | 
127 | Use instead of *numerical*.
128 | 
129 | For the keypad, use *numeric keypad*. Don't use *numerical keypad* or *numeric keyboard*.
130 | 


--------------------------------------------------------------------------------
/docs/8-word-list/numbers.md:
--------------------------------------------------------------------------------
 1 | # Numbers
 2 | 
 3 | ## 24/7, 24x7
 4 | 
 5 | Don't use. Instead use 24 hours a day, seven days a week.
 6 | 
 7 | For more information, see [Dates and times](https://make.wordpress.org/docs/style-guide/formatting/dates-times/).
 8 | 
 9 | ## 2D
10 | 
11 | Abbreviation for *two-dimensional*. Spell out the first mention of the term as *two-dimensional*; on subsequent mentions, use *2D*.
12 | 
13 | Always hyphenate *two-dimensional*. Don't hyphenate the abbreviation as *2-D*.
14 | 
15 | For more information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
16 | 
17 | ## 3D
18 | 
19 | Abbreviation for *three-dimensional*. Spell out the first mention of the term as *three-dimensional*; on subsequent mentions, use *3D*.
20 | 
21 | Always hyphenate *three-dimensional*. Don't hyphenate the abbreviation as *3-D*.
22 | 
23 | For more information, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
24 | 


--------------------------------------------------------------------------------
/docs/8-word-list/o.md:
--------------------------------------------------------------------------------
  1 | # O
  2 | 
  3 | ## O2
  4 | 
  5 | Capitalize.
  6 | 
  7 | Not *o2, O-2,* or *O 2*.
  8 | 
  9 | See also [P2](https://make.wordpress.org/docs/style-guide/word-list/p/#p2).
 10 | 
 11 | ## object
 12 | 
 13 | Don't use as a synonym for *thing* or *item*. Instead, refer to a specific object or use a contextually relevant and accurate term.
 14 | 
 15 | ## obsolete
 16 | 
 17 | Don't use as a verb. Instead, use a phrase such as *make obsolete*.
 18 | 
 19 | ## of
 20 | 
 21 | Don't use after another preposition in phrases such as *off of* or *outside of*.
 22 | 
 23 | ## offline
 24 | 
 25 | One word, both as an adjective and adverb. Not *off line* or *off-line*.
 26 | 
 27 | Use only to describe not being connected to the internet or a particular network.
 28 | 
 29 | ## off-premises, on-premises
 30 | 
 31 | Not *off-premise* and *on-premise*. Hyphenate.
 32 | 
 33 | See also [offsite](#offsite), [onsite](#onsite).
 34 | 
 35 | ## offscreen
 36 | 
 37 | One word. Not *off screen* or *off-screen*.
 38 | 
 39 | See also [onscreen](#onscreen).
 40 | 
 41 | ## offsite
 42 | 
 43 | One word. Not *off site* or *off-site*.
 44 | 
 45 | See also [off-premises, on-premises](#off-premises-on-premises), [onsite](#onsite).
 46 | 
 47 | ## OK
 48 | 
 49 | Not *ok, okay, Okay, alright*, or *all right*. Use uppercase.
 50 | 
 51 | ## older
 52 | 
 53 | Don't use as a synonym for *earlier* to refer to older versions of a product or software. Instead, use *earlier*.
 54 | 
 55 | See also [earlier](https://make.wordpress.org/docs/style-guide/word-list/e/#earlier), [later](https://make.wordpress.org/docs/style-guide/word-list/l/#later).
 56 | 
 57 | ## once
 58 | 
 59 | Use only to describe *one time*. Don't use as a synonym for *after* or *when*.
 60 | 
 61 | ## online
 62 | 
 63 | One word, both as an adjective and adverb. Not *on line* or *on-line*.
 64 | 
 65 | Use to describe content or services that are available on the internet or a particular network. It is OK to use *online* to describe being on or connected to the internet or a particular network; but in most cases, use a contextually relevant and accurate term such as *signed in* or *connected to the internet*.
 66 | 
 67 | See also [offline](#offline).
 68 | 
 69 | ## onscreen
 70 | 
 71 | One word. Not *on screen* or *on-screen*.
 72 | 
 73 | See also [offscreen](#offscreen).
 74 | 
 75 | ## onsite
 76 | 
 77 | One word. Not *on site* or *on-site*.
 78 | 
 79 | See also [off-premises, on-premises](#off-premises-on-premises), [offsite](#offsite).
 80 | 
 81 | ## onto, on to
 82 | 
 83 | Use *onto* to refer to moving something to a position on top of something else.
 84 | 
 85 | Use *on to* when *on* is part of the verb.
 86 | 
 87 | **Examples**  
 88 | [tip] **Recommended:** Drag the image onto the desktop. [/tip]  
 89 | [tip] **Recommended:** Pass on to the next item. [/tip]  
 90 | 
 91 | See also [into, in to](https://make.wordpress.org/docs/style-guide/word-list/i/#into-in-to).
 92 | 
 93 | ## open
 94 | 
 95 | Use *open*, not *start* or *launch* to describe opening a program, application, folder, or a similar target. Don't use *open* for menus and commands.
 96 | 
 97 | Use *open*, not *opened*, to describe the open state, such as *an open folder*.
 98 | 
 99 | For more information, see [Interaction verbs]https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#open).
100 | 
101 | See also [close](https://make.wordpress.org/docs/style-guide/word-list/c/#close).
102 | 
103 | ## open source
104 | 
105 | Two words, both as an adjective and verb. Not *opensource* or *open-source*. Use lowercase and don't hyphenate.
106 | 
107 | ## option
108 | 
109 | OK to use in developer documentation and for a technical audience.
110 | 
111 | In a command-line context, use *option* instead of *flag, argument*, or *parameter*.
112 | 
113 | For more information, see [Command-line syntax](https://make.wordpress.org/docs/style-guide/developer-content/command-line-syntax/).
114 | 
115 | In general, emphasize on the task to be accomplished, rather than how the user should interact with the UI element. Refer to an option by its label. If you have to use a descriptor, use *option* or *option button*.
116 | 
117 | For more information, see [UI elements](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/).
118 | 
119 | ## OS, operating system
120 | 
121 | Initialism for *operating system*. Use uppercase for the initialism.
122 | 
123 | For the spelled out version, use two words as a noun, and hyphenate as an adjective.
124 | 
125 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
126 | 
127 | ## output
128 | 
129 | Avoid as a verb. Instead, use *write to, display on, print on, print to*, or a contextually relevant and accurate term.
130 | 
131 | ## outside
132 | 
133 | Not *outside of*.
134 | 
135 | ## over
136 | 
137 | Use to refer to a location or position above something.
138 | 
139 | In context of quantities, don't use as a synonym for *more than*.
140 | 
141 | Don't use to refer to version numbers. Instead, use *later*.
142 | 
143 | See also [later](https://make.wordpress.org/docs/style-guide/word-list/l/#later), [more than](https://make.wordpress.org/docs/style-guide/word-list/m/#more-than)
144 | 
145 | ## ⁠override
146 | 
147 | One word. Not *over ride* or *over-ride*.
148 | 
149 | ## overwrite
150 | 
151 | Use only to describe existing data with new data. Use *replace* to describe replacing an existing file with a new one that has the same name.
152 | 
153 | Don't use as a synonym for *type over*.
154 | 


--------------------------------------------------------------------------------
/docs/8-word-list/q.md:
--------------------------------------------------------------------------------
 1 | # Q
 2 | 
 3 | ## quality
 4 | 
 5 | Don't use *quality* by itself as an adjective. Instead, use a modifier and hyphenate. For example, *high-quality, studio-quality*.
 6 | 
 7 | ## quick, quickly
 8 | 
 9 | Avoid using. *Quick* or *quickly* is a relative term, and in most cases, you can express the same meaning of a sentence without using these terms.
10 | 
11 | ## quit
12 | 
13 | Don't use to refer to the action of closing a program, window, or a connection. Instead use *close, stop*, or *end*.
14 | 
15 | See also [close](https://make.wordpress.org/docs/style-guide/word-list/c/#close), [end](https://make.wordpress.org/docs/style-guide/word-list/e/#end), [exit](https://make.wordpress.org/docs/style-guide/word-list/e/#exit), [interrupt](https://make.wordpress.org/docs/style-guide/word-list/i/#interrupt), [stop](https://make.wordpress.org/docs/style-guide/word-list/s/#stop).
16 | 
17 | ## quotation marks
18 | 
19 | Not *quotes* or *quote marks*. *Quote* is a verb, and *quotation* is an adjective or a noun.
20 | 
21 | For more information, see [Quotation marks](https://make.wordpress.org/docs/style-guide/punctuation/quotation-marks/).
22 | 
23 | ## quote
24 | 
25 | Don't use *quote* to refer to cited content. Instead, use *quotation*.
26 | 


--------------------------------------------------------------------------------
/docs/8-word-list/symbols.md:
--------------------------------------------------------------------------------
  1 | # Symbols
  2 | 
  3 | ## & (ampersand)
  4 | 
  5 | Don't use *&* instead of *and* in most cases. It is acceptable to use *&* when referencing UI elements that use *&*, in places with space constraints, such as tables and UI element labels.
  6 | 
  7 | The use of `&` in code is completely fine.
  8 | 
  9 | ## <> (angle brackets)
 10 | 
 11 | Use *angle brackets* to describe the *<* and *>* symbols. Don’t use *angle brackets* when you mean *brackets* ([]).
 12 | 
 13 | Use *opening bracket* and *closing bracket* to distinguish between the left and right brackets.
 14 | 
 15 | See also [[] (brackets)](#brackets).
 16 | 
 17 | ## * (asterisk)
 18 | 
 19 | OK to use in developer documentation and for a technical audience.
 20 | 
 21 | Don't use an asterisk instead of the multiplication sign, or while expressing dimensions. Instead use the multiplication sign.
 22 | 
 23 | For more information, see [Dimensions](https://make.wordpress.org/docs/style-guide/formatting/numbers/#dimensions) and [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/).
 24 | 
 25 | See also [× (multiplication sign)](https://make.wordpress.org/docs/style-guide/word-list/symbols/#x-multiplication-sign), [x](https://make.wordpress.org/docs/style-guide/word-list/x/#x)
 26 | 
 27 | ## @ (at sign)
 28 | 
 29 | Pronounced as *at sign*.
 30 | 
 31 | In most cases don't spell out as *at sign*.
 32 | 
 33 | ## {} (braces)
 34 | 
 35 | Use *braces* to describe the *{}* symbols. Don't use *braces*.
 36 | 
 37 | Use *opening braces* and *closing braces* to distinguish between the left and right braces.
 38 | 
 39 | ## [] (brackets)
 40 | 
 41 | Use *brackets* to describe the *[* and *]* symbols. Don’t use *brackets* when you mean *angle brackets* (<>).
 42 | 
 43 | Use *opening bracket* and *closing brackets* to distinguish between the left and right brackets.
 44 | 
 45 | See also [<> (angle brackets)](#angle-brackets).
 46 | 
 47 | ## º (degree symbol)
 48 | 
 49 | Use degree symbol to describe the *º* symbol.
 50 | 
 51 | It's OK to use *degree* or *degrees* instead of the degree symbol.
 52 | 
 53 | Don't insert a space between the numerical value, the degree symbol and the unit of measurement.
 54 | 
 55 | **Examples**  
 56 | [warning] **Not recommended:** 70º F [/warning]  
 57 | [warning] **Not recommended:** 70 ºF [/warning]  
 58 | [warning] **Not recommended:** 70 º F [/warning]  
 59 | [tip] **Recommended:** 70ºF [/tip]  
 60 | 
 61 | ## ÷ (division sign)
 62 | 
 63 | Not *division symbol*.
 64 | 
 65 | For more information about fractions and division, see [Numbers](https://make.wordpress.org/docs/style-guide/formatting/numbers/).
 66 | 
 67 | ## = (equal sign)
 68 | 
 69 | Not *equal’s sign, equals sign*, or *equal symbol*.
 70 | 
 71 | Insert a space before and after the equal sign.
 72 | 
 73 | ## .htaccess
 74 | 
 75 | Use code font.
 76 | 
 77 | For more information, see [Filenames](https://make.wordpress.org/docs/style-guide/formatting/filenames/).
 78 | 
 79 | ## – (minus sign)
 80 | 
 81 | Not *minus symbol*.
 82 | 
 83 | Use an en dash to indicate the minus sign. While writing an equation with a minus sign, insert a space before and after the minus sign (en dash).
 84 | 
 85 | For more information, see [En dashes](https://make.wordpress.org/docs/style-guide/punctuation/dashes/#en-dashes).
 86 | 
 87 | ## × (multiplication sign)
 88 | 
 89 | Not *multiplication symbol*.
 90 | 
 91 | It is OK to use *x* instead of the multiplication sign (×).
 92 | 
 93 | For more information, see [Dimensions](https://make.wordpress.org/docs/style-guide/formatting/numbers/#dimensions) and [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/).
 94 | 
 95 | See also [x](https://make.wordpress.org/docs/style-guide/word-list/x/#x)
 96 | 
 97 | ## # (number sign)
 98 | 
 99 | Not *number symbol*.
100 | 
101 | Always spell out *number* in *number sign*. Don't use *pound sign* or *number symbol*.
102 | 
103 | **Examples**  
104 | [warning] **Not recommended:** #99 [/warning]  
105 | [tip] **Recommended:** number 99 [/tip]  
106 | 
107 | Don't use the number sign preceding a numeral. Instead, spell out *number*. It's acceptable to abbreviate *number* as *no.*, but consider a global audience; as many languages don't abbreviate *number* as *no.* which may cause confusion.
108 | 
109 | It's OK to use the *#* symbol to indicate a hashtag. Don't use *number sign* to refer to the hashtag.
110 | 
111 | See also [number](https://make.wordpress.org/docs/style-guide/word-list/n/#number).
112 | 
113 | ## + (plus sign)
114 | 
115 | Not *plus symbol*.
116 | 
117 | Don't use the plus sign as a synonym for terms such as *and, plus,* and *over*.
118 | 
119 | It's OK to use the plus sign in UI, tables, or headings where space is limited.
120 | 


--------------------------------------------------------------------------------
/docs/8-word-list/v.md:
--------------------------------------------------------------------------------
 1 | # V
 2 | 
 3 | ## version, v.
 4 | 
 5 | Use lowercase when using *v* or *v.* for indicating a version.
 6 | 
 7 | Don't use *version* as a verb such as *versioning*.
 8 | 
 9 | ## versus, vs., v.
10 | 
11 | Avoid using *vs.* or *v.* as an abbreviation for *versus*. Acceptable to use in UI, tables, or headings where space is limited. Instead, use the unabbreviated term *versus* or other relevant phrasing such as *compared to*.
12 | 
13 | ## very
14 | 
15 | Avoid using.
16 | 
17 | ## via
18 | 
19 | Avoid using. Instead use *by, from, through, using*, or *with*. Acceptable to use in UI, tables, or headings where space is limited.
20 | 
21 | ## vice versa
22 | 
23 | Don't use. Instead use *conversely, otherwise, the other way round,* or *on the contrary*.
24 | 
25 | In some contexts, *vice versa* is confusing or ambiguous in determining which two opposite things are swapped with each other. In such cases, describe what two things are swapped without ambiguity.
26 | 
27 | ## video card
28 | 
29 | Use *video card* instead of *video adapter, display adapter, graphics adapter, graphics card*, or *graphics board*.
30 | 
31 | ## video display
32 | 
33 | Don't use.
34 | 
35 | ## video driver
36 | 
37 | Use *video driver* instead of *display driver* or *graphics driver*.
38 | 
39 | ## virtual
40 | 
41 | OK to use in developer documentation and for a technical audience. Avoid using in user documentation and for a general audience.
42 | 
43 | Use only to refer to a device or service that doesn't physically exist or appears to be something it's not. For example, a *virtual machine (VM)* isn't an actual machine; it's a machine that emulates a real computer.
44 | 
45 | ## virtualize
46 | 
47 | OK to use in developer documentation and for a technical audience. Avoid using in user documentation and for a general audience.
48 | 
49 | ## virtual machine, VM
50 | 
51 | Use *virtual machine* when introducing the term for the first time. On subsequent mentions, it is OK to use *VM* or *VM instance*.
52 | 
53 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
54 | 
55 | ## visit
56 | 
57 | Don't use to refer to the action of opening a website or webpage. Instead, use *go to*.
58 | 
59 | For more information, see [Interaction verbs](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#go-to).
60 | 
61 | ## volume (disk)
62 | 
63 | OK to use in developer documentation and for a technical audience. Avoid using in user documentation and for a general audience; instead, use *disk*.
64 | 
65 | To refer to storage that may include different types of disks, just use *disk*. You can also refer to a specific type of disk such as *solid-state drive, hard-disk,* or *flash storage*.
66 | 
67 | See also [disk](https://make.wordpress.org/docs/style-guide/word-list/d/#disk).
68 | 
69 | ## VPN
70 | 
71 | Initialism for *Virtual Private Network*. Use uppercase.
72 | 
73 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
74 | 
75 | ## VVV
76 | 
77 | Initialism for *Varying Vagrant Vagrants*. Use uppercase.
78 | 
79 | For more information about spelling out abbreviations, see [Abbreviations](https://make.wordpress.org/docs/style-guide/language-grammar/abbreviations/).
80 | 


--------------------------------------------------------------------------------
/docs/8-word-list/x.md:
--------------------------------------------------------------------------------
 1 | # X
 2 | 
 3 | ## x
 4 | 
 5 | Use lowercase and use italic formatting when using as a variable or placeholder.
 6 | 
 7 | It is OK to use *x* instead of the multiplication sign (×).
 8 | 
 9 | For more information, see [Dimensions](https://make.wordpress.org/docs/style-guide/formatting/numbers/#dimensions) and [Placeholders](https://make.wordpress.org/docs/style-guide/developer-content/placeholders/).
10 | 
11 | ## x-
12 | 
13 | Hyphenate all words that begin with *x* used as a separate letter, such as *x-coordinate* and *x-axis*.
14 | 
15 | Don't use italic formatting for the *x* in these words unless the entire word is italic.
16 | 
17 | ## x-axis
18 | 
19 | Use lowercase and hyphenate.
20 | 
21 | Don't use italic formatting for the *x* in *x-axis* unless the entire word is italic.
22 | 
23 | ## x-coordinate
24 | 
25 | Use lowercase and hyphenate.
26 | 
27 | Don't use italic formatting for the *x* in *x-coordinate* unless the entire word is italic.
28 | 
29 | ## XML
30 | 
31 | Initialism for *Extensible Markup Language*. Use uppercase.
32 | 
33 | Don't use a filename extension to refer to a type of file. For example, use *XML file* rather than *.xml file*.
34 | 
35 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
36 | 


--------------------------------------------------------------------------------
/docs/8-word-list/y.md:
--------------------------------------------------------------------------------
 1 | # Y
 2 | 
 3 | ## y-
 4 | 
 5 | Hyphenate all words that begin with *y* used as a separate letter, such as *y-coordinate* and *y-axis*.
 6 | 
 7 | Don't use italic formatting for the *y* in these words unless the entire word is italic.
 8 | 
 9 | ## y-axis
10 | 
11 | Use lowercase and hyphenate.
12 | 
13 | Don't use italic formatting for the *y* in *y-axis* unless the entire word is italic.
14 | 
15 | ## y-coordinate
16 | 
17 | Use lowercase and hyphenate.
18 | 
19 | Don't use italic formatting for the *y* in *y-coordinate* unless the entire word is italic.
20 | 
21 | ## YAML
22 | 
23 | Recursive acronym for *YAML Ain't Markup Language*. Use uppercase.
24 | 
25 | Don't use a filename extension to refer to a type of file. For example, use *YAML file* rather than *.yaml file*.
26 | 
27 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
28 | 


--------------------------------------------------------------------------------
/docs/8-word-list/z.md:
--------------------------------------------------------------------------------
 1 | # Z
 2 | 
 3 | ## z-
 4 | 
 5 | Hyphenate all words that begin with *z* used as a separate letter, such as *z-coordinate, z-test* and *z-axis*.
 6 | 
 7 | Don't use italic formatting for the *z* in these words unless the entire word is italic.
 8 | 
 9 | ## z-axis
10 | 
11 | Use lowercase and hyphenate.
12 | 
13 | Don't use italic formatting for the *z* in *z-axis* unless the entire word is italic.
14 | 
15 | ## zero, zeros
16 | 
17 | Use *zeros*, not *zeroes*, as the plural of *zero*.
18 | 
19 | When a measurement is zero, use the plural form of the spelled-out unit of measurement.
20 | 
21 | **Examples**  
22 | [tip] **Recommended:** 0 kilobytes [/tip]  
23 | [tip] **Recommended:** 0 KB [/tip]  
24 | 
25 | ## zip
26 | 
27 | Don't use a filename extension to refer to a type of file. For example, use *zip file* rather than *.zip file*.
28 | 
29 | Don't use *zip* or *unzip* as a verb. Instead, use *compress* and *extract*.
30 | 
31 | For more information, see [Referring to file types](https://make.wordpress.org/docs/style-guide/formatting/filenames/#referring-to-file-types).
32 | 
33 | ## ZIP code
34 | 
35 | OK to use in content intended for US locales and audiences. Otherwise, use *postal code*.
36 | 
37 | Use uppercase capitalization for *ZIP*.
38 | 
39 | ## zoom
40 | 
41 | OK to use *zoom, zoom in, zoom out*.
42 | 
43 | For more information, see [Interaction verbs](https://make.wordpress.org/docs/style-guide/developer-content/ui-elements/#zoom).
44 | 


--------------------------------------------------------------------------------