For additional style guidance not covered in the topics below, refer to:
For terms used in VIP Documentation that require additional definition or supplementary understanding, link to the following sources whenever possible:
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.
- Articles are written in the 3rd-person voice.
Example: “Add an embed block to
- 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 filewith”
- 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
- 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.
- References to a single directory should have a “/” appended to their name.
- 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.
digto retrieve DNS information”
- Functions should be styled with “Inline code” formatting and should retain upper and lower case formatting as established from their source.
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.
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:
home value by running the command:
vip @example.production -- wp option get home
Which will return a value similar to this:
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
Precede VIP-CLI command examples with the “VIP-CLI command examples” reusable block and format the command examples with
VIP-CLI command examples
For demonstration purposes, the
mytestsite and the
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 with
production 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
mytestsite and the
production are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.
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).
When referring to the domain of a local environment, use
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.
- Topic summary
- Prerequisites (installed tools, user access, etc.)
- Roles and permissions
- Steps to enable or use
- Available options
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:
string || integer || path ||other || Values not accepted
Added in version:
- “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-admincan be used.
|WordPress VIP||WordPress.com VIP|
|WordPress VIP Platform||VIP Go|
|VIP Support||VIP support|
|VIP Dashboard||VIP dashboard|
|Elasticsearch||ES, Elastic Search|
|Node.js||Node, NodeJS, Node JS|
|NGINX||Nginx, nginx (except when referred to in code, e.g. |
|geotargeting||geo targeting, geo-targeting|
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:
and would be more easily identified and memorable as:
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.