WordPress VIP’s Documentation Style Guide

For additional style guidance not covered in the topics below, refer to:

• Make WordPress Documentation

External links

Definition of terms

For terms used in VIP Documentation that require additional definition or supplementary understanding, link to the following sources whenever possible:

1. MDN Web Docs
2. W3C

Third-party software and services

Though mentions (i.e. “endorsements”) of specific third-party software and services are discouraged, there may be article topics that benefit by including links to third-party software and services that are helpful to customers. In those cases, a link to those resources is sufficient; do not provide additional instructions for their installation or use.

Writing style

Language style

• Articles are written in the 3rd-person voice.
  Example: “Add an embed block to your the page.”
• Use American English for spelling and punctuation styles, or consider using a different word that doesn’t have a different spelling in other English variants.
• Use sentence case (not title case) for docs titles and subheadings.
  Example: “Introduction to the launch experience” rather than “Introduction to the Launch Experience.”
• When referring to files or directories, the text formatting eliminates the need to include articles such as “the” and clarifying nouns such as “file” or “directory”.
  Example: “files stored in the /wp-content/uploads/ directory” or “edit the /config/config.yml file with”

Writing tips

• Consider that this might be the first VIP Docs page the reader has seen. They may have arrived here via a Google search or another website. Give the reader enough context about the topic and link words and phrases to other relevant Docs articles as often as possible.
• Our target audience has a wide range of roles and abilities. Use language that is understandable even by readers with little technical knowledge and readers whose first language might not be English.
• Consider notes and sections that provide insights, tips, or cautionary information to expand on topics with context that would be relevant to the reader.
• When providing specific direction, best practices, or requirements, we recommend including a description of the potential consequences or impacts of not following the provided guidance. This can help seed additional search keywords into the document and provide better context when support links to the documentation.
• Always write a conceptual, high-level introduction to the topic first, above any H2 subheading.

Formatting

Acronyms

Phrases that are more familiarly known in their acronym form can be used. The first time an acronym appears on any page, the full phrase must be included, followed by its acronym in parentheticals.

Example: VIP can support either the www or non-www variant of your domain as the fully qualified domain name (FQDN).

After that, the acronym can be used for the remainder of the page.

When deciding if a term is common, consider the impact on translation and future internationalization (i18n) efforts.

Measurements

“There is a space between the numerical value and unit symbol.” – as per #15 Unit Spacing in The NIST Reference on Constants, Units, and Uncertainty

Correct example: 1 GB

Incorrect example: 1GB

Visual style

• Use the H2 style for main headings to be programmatically listed in the articles table of contents in the upper right of the Desktop view.
• File names and directory paths should be stylized as code per the HTML spec.
  Example: “/wp-content/uploads/“
• References to a single directory should have a trailing slash (eg. “/” appended) to the name.
  Example: “uploads/“
• References to repositories should appear without forward slashes and not be formatted in any way. The first appearance of a repository in article content should link to the URL of the repository source whenever possible.
  Example: “vip-go-mu-plugins” followed by “vip-go-mu-plugins”
• Inline references to functions and command line operations should be formatted as inline code.
  Example: “Use dig to retrieve DNS information.”
• Functions should be styled with “Inline code” formatting and retain upper and lower case formatting as established from their source.
  Example: WP_Query (not WP_query)
• Domain names are code-formatted when appearing in documentation content.
  Example:  www.domain.com 
• When referring to the domain of a local environment, use localhost or http://localhost. 
• When referring to an environment by type it is lowercase with no styling.
  Example: “The develop environment is the child of the production environment.”

Command examples

Use the “Preformatted” block for CLI/command examples.

vip @example.production -- wp site list

It is preferred to display examples of returned output from commands in a separate “Preformatted” block, with a leading sentence before it. For example:

Query the home value by running the command:

vip @example.production -- wp option get home

Which will return a value similar to this:

https://www.example.com

When displaying multiple commands or including output in the same block, prepend commands with $

$ vip @example.production -- wp option get home
https://www.example.com

VIP-CLI command examples

Precede VIP-CLI command examples with the “VIP-CLI command examples” reusable block and format the command examples with @example-app.develop:

In some cases, the examples may require @<app>.<env> to be formatted withproduction as the env, in which case the “VIP-CLI command examples (prod)” reusable block can be used instead:

Code examples

Use the “VIP Docs Code” block for code snippets.

Inline references to functions should include ().

Use strict type declarations in PHP code examples to encourage strongly typed code to help customers reduce bugs (typically appearing as PHP Warnings or logic errors) and better prepare them for PHP 8 compatibility (which steps up the strongly-typed nature for native PHP functions).

Patterning

Article content

When writing a Documentation article, present the information in the order shown below. Some of these information types might not be relevant to the Documentation topic and can be skipped.

1. Topic summary
2. Prerequisites (installed tools, user access, etc.)
3. Limitations
4. Roles and permissions
5. Steps to enable or use
6. Available options
7. Troubleshooting

VIP-CLI commands and options

All available commands and command options should have a presence in the Documentation. Include information items for each command and command option in the following order, omitting the items that are not applicable:

<command-or-option>

Accepted values: string || integer || path ||other || Values not accepted
Default value: <value>
Added in version: <vip-cli-release-version>

Terminology

Brand terminology for Automattic and WordPress VIP

Correct	Incorrect
Jetpack	JetPack
WordPress VIP	WordPress.com VIP, WPVIP
WordPress VIP Platform	VIP Go
VIP Support	VIP support
VIP-CLI	VIP CLI
WooCommerce	WC, Woo
WP-CLI	WP CLI
VIP Dashboard	VIP dashboard

WordPress terminology

• WordPress Core appears in title case.
• “WordPress Admin dashboard” should be presented in its complete form the first time it appears in an article, followed by its abbreviated form in parentheses (“WP Admin”). Thereafter the abbreviated form can be used for any reference to the WordPress Admin dashboard within the same article.
• When referring to the URL of the WordPress Admin dashboard, the shortened form wp-admin can be used.
• WordPress Multisite: A WordPress installation that supports more than one site on the same code and database. WordPress.com is the world’s largest Multisite installation.
• Network: A collection of sites that exist on a WordPress multisite environment. (With a lowercase n. The n is only capitalized where “network” is a proper noun, such as the title of the “Network Sites” panel in the VIP Dashboard.)
• Network site (Incorrect terminology: “subsite”): A site on a WordPress multisite network.
• Main site (Incorrect terminology: “root site”): The first site (ID 1) on a WordPress multisite network.
• The term site is used to refer to a WordPress single site, or a site on a WordPress multisite network.
• Block editor (Incorrect terminology: “Gutenberg”): The default WordPress editing user interface that uses blocks to build content, mainly in posts and pages.

Industry terminology

Correct	Incorrect
Elasticsearch	ES, Elastic Search
email	e-mail
JavaScript	Javascript
Memcached	memcached, memcache (Memcache is a thing, but VIP platform uses Memcached)
Node.js	Node, NodeJS, Node JS
NGINX	Nginx, nginx (except when referred to in code, e.g. nginx)
pull request	PR
geotargeting	geo targeting, geo-targeting
WebSockets	websockets

Structure

Permalink slugs

Groom permalink slugs to be relevant to the article but as concise as possible.
For example, an article titled “Customize the VIP Code Analysis Bot” will have an automatically generated permalink of:
docs.wpvip.com/customize-the-vip-code-analysis-bot
and would be more easily identified and memorable as:
docs.wpvip.com/customize-the-bot

Atomizing the Docs

Articles that cover too many topics in one place can make it difficult for users to find the information they are looking for. “Atomizing” the Docs refers to breaking down extensive articles into a group of smaller related articles. This group of articles often has a main “landing page” with a high-level overview of the group of articles, and the descriptive text provides links to the related articles that a user will find relevant. These groups of articles can be considered an information “molecule” formed by the smaller, atomized articles.

Breaking out smaller chunks of content into their own articles makes it easier to link to specific topics rather than relying on links to more extensive articles with anchor tags. This more specific linking approach is helpful to our Support team but is also useful for cross-linking articles throughout the Docs site.