Skip to content

WordPress VIP’s Documentation Style Guide

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

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 spellings 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

  • Our target audience has a range of roles and abilities. Use language that is understandable even by readers who do not have a lot of technical knowledge and readers whose first language might not be English.
  • Consider that this might be the first VIP Docs page the reader has seen. They may have arrived there via a Google search or another website. Give the reader enough context about the topic, as well as linking words and phrases to other relevant Docs articles as often as possible.
  • 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 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

Visual styles

  • Use the H2 style for main headings in order for them 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 “Keyboard input” and italicized.
    Example: “/wp-content/uploads/
  • References to a single directory should have a “/” appended to their 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 should retain upper and lower case formatting as established from their source.
    Example: WP_Query (not WP_query)

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).

Thereafter, the acronym can used on its own for the remainder of the page.

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

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 @mytestsite.develop:

VIP-CLI command examples

For demonstration purposes, the <app-alias> value mytestsite and the <env> value develop are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.

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:

VIP-CLI command examples

For demonstration purposes, the <app-alias> value mytestsite and the <env> value production are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.

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 (which typically appear 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).

Domains

When referring to the domain of a local environment, use localhost or http://localhost

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

Reference to components and features

  • WordPress Admin dashboard” should be presented in its full 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.

VIP brand terminology

CorrectIncorrect
WordPress VIPWordPress.com VIP
WordPress VIP PlatformVIP Go
VIP SupportVIP support
VIP-CLIVIP CLI
WP-CLIWP CLI
VIP DashboardVIP dashboard

Industry terminology

CorrectIncorrect
ElasticsearchES, Elastic Search
JavaScriptJavascript
Node.jsNode, NodeJS, Node JS
NGINXNginx, nginx (except when referred to in code, e.g. nginx)
pull requestPR
geotargetinggeo targeting, geo-targeting
WebSocketswebsockets

Structure

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 large 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 larger articles with anchor tags. This more specific linking approach is useful to our Support team, but is also useful for cross-linking articles throughout the Docs site.