woocommerce/docs/style-guide.md

post_title
Technical documentation style guide

This style guide is intended to provide guidelines for creating effective and user-friendly tutorials and how-to guides for WooCommerce technical documentation that will live in repo and be editable and iterative by open source contributors and WooCommerce teams.

Writing style

Language style

• It’s important to use clear and concise language that is easy to understand. Use active voice and avoid using jargon or technical terms that may be unfamiliar to the user. The tone should be friendly and approachable, and should encourage the user to take action.

• Articles are written in the 3rd-person voice. Example: “Add an embed block to your 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

• Our target audience has a range of roles and abilities. When creating a tutorial or how-to guide, it’s important to consider the intended audience. Are they beginners or advanced users? What is their technical background? Understanding the audience can help guide the level of detail and the choice of language used in the guide.

• Use language understable even by readers with little technical knowledge and readers whose first language might not be English.

• Consider that this might be the first WooCommerce documentation 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.

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

Tutorials

Tutorials are comprehensive and designed to teach a new skill or concept.

You are the teacher, and you are responsible for what the student will do. Under your instruction, the student will execute a series of actions to achieve some end.

Divio Framework on Tutorial Writing

How-to guides

How-to guides are focused and specific, providing instructions on how to accomplish a particular task or solve a particular problem.

How-to guides are wholly distinct from tutorials and must not be confused with them:

• A tutorial is what you decide a beginner needs to know.
• A how-to guide is an answer to a question that only a user with some experience could even formulate.

Divio Framework on How-to-Guide Writing

Custom Linting Rules

At WooCommerce, we're dedicated to maintaining a consistent and high-quality standard for our technical documentation. Our documents primarily adhere to the linting rules provided by markdownlint. To assist our contributors, we've detailed our custom configurations and exceptions below.

Note: While we've outlined specific rules above, all other default linting rules from markdownlint apply unless otherwise stated. We've only highlighted custom configurations or exceptions here. For a complete list of markdownlint rules, you can refer to this link.

1. Headings Style:

   • Use the ATX-style (#) for headers.

---

# This is an H1

---

## This is an H2
```

Reference: MD003

2. List Indentation:

   • Indent list items with 4 spaces.

   - Item 1
       - Subitem 1.1
   

   Reference: MD007

3. Line Length:

   • No specific restriction on the line length, but keep paragraphs and sentences readable.

   Reference: MD013

4. Multiple Headings with the Same Content:

   • Multiple headings with the same content are permissible as long as they are not siblings.

   Reference: MD024

5. Inline HTML:

   • Only the video element is allowed when using inline HTML.

   <video src="path_to_video.mp4" controls></video>
   

   Reference: MD033

6. Tabs and Whitespace:

   • We're flexible with the use of hard tabs and trailing whitespace. However, for consistency, we recommend using spaces over tabs and avoiding trailing whitespaces.

   Reference: no-hard-tabs & whitespace

Formatting

Visual style

• Use the H2 style for main headings to be programmatically listed in the articles table of contents.
• 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: “woocommerce-blocks” followed by “woocommerce-blocks”
• 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)

Visual aids

Visual aids such as screenshots, diagrams, code snippets and videos can be very helpful in a how-to guide. They provide a visual reference that can help the user understand the instructions more easily. When including visual aids, be sure to label them clearly and provide a caption or description that explains what is being shown.

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: We’ve enhanced the querying functionality in WooCommerce with the introduction of High Performance Order Storage (HPOS).

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.

Patterning

Article content

When creating a how-to guide, it’s important to use a consistent and easy-to-follow format. Here is a suggested template for a software how-to guide:

Introduction: Provide an overview of the task or feature that the guide covers.

Prerequisites: List any prerequisites that are required to complete the task or use the feature.

Step-by-step instructions: Provide detailed, step-by-step instructions for completing the task or using the feature. Use numbered steps and include screenshots or other visual aids where appropriate.

Troubleshooting: Include a troubleshooting section that addresses common issues or errors that users may encounter.

Conclusion: Summarize the key points covered in the guide and provide any additional resources or references that may be helpful.

Terminology

Reference to components and features

• “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.

Testing

Before publishing a tutorial or guide, it’s important to test it thoroughly to ensure that the instructions are accurate and easy to follow.

Structure

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.