Mission of documentation

  • To inform
  • To guide and answer
  • To educate and empower 

How a style guide supports documentation

  • Provides consistent presentation and experience for users
  • Creates a unified voice for multiple authors
  • Saves time and resources with clearly documented decisions 

Voice and tone

  • Conversational, friendly, and global

Writing style

  • Clean and clear

Types of documentation

We offer two types of documentation — one for all users and one for our developer community, those with more technical experience. They typically cover:

User documentation

  • Setup and configuration
  • Use cases
  • Comparisons
  • Video tutorials

Developer documentation

  • Hooks and Filters
  • Function reference
  • Code snippets
  • API

Writing documentation

A general overview of crafting WordPress.com marketplace product documentation.

Recommended workflow

Organize — Think about your audience, gather notes, and make an outline. Know your outcome.

Draft — Follow the template as described in the standard WordPress plugin readme.txt file. 

We also suggest including use cases, tables, and comparisons to assist users to set up or select the appropriate product. Clear, succinct information helps users make better decisions.

Add images — 

  • Use Droplr or a similar application to take high-quality screenshots. 
  • Annotate screenshots as needed with arrows and boxes. 
  • Use a meaningful name for the image. For example, checkout-field-editor-settings.png or subscriptions-woocommerce-shortcodes.png. This is important for SEO and accessibility. 
  • Avoid meaningless file names such as screenshot-2.png. 
  • Make sure your screenshots and videos match your written documentation exactly.For example, the interface and option names used in the screenshot should match the instructions in the documentation. 

Review — Review to ensure that your documents adhere to the formatting, grammar, punctuation, and style requirements.

Proofread — Always proofread for spelling, grammar, and punctuation. 

Outline clear steps

With user documentation, you’re writing for a non-technical audience. Here are a few tips on creating clear documentation:

  • Assume the user has zero experience and technical expertise on how to use your plugin/extension.
  • List every single step. Help users be successful with your product. Ensure that you’ve outlined every step in a set of instructions.  
  • Use a new step for each separate action the user must take. 
  • Use bold print to highlight:
    • The verb — ideally, an imperative — or the main focus of the step
    • The path — e.g., WordPress.com > Settings
  • Test your documentation thoroughly. Have a new user set up the product. Were they able to work through the documentation successfully? Were there any confusing or missing pieces of information? Would a screenshot or video be helpful in certain places?

A note on custom code/CSS. Our WordPress.com Support Policy explicitly says that customization is beyond the scope of support we provide. Deciding to include information on custom code and CSS in your docs is a long-term choice you need to make regarding support, maintenance, troubleshooting, and managing customer expectations.

Include helpful screenshots

A good screenshot in the right place can make it easier for users to follow the steps in order.

When adding a screenshot:

  • Write out the instructions in the accompanying text. This is critically important to ensure that anyone accessing your document via screen reader received the information they need to set up your product. Be sure to write descriptive alt text for all screenshots. 
  • Use the default WordPress Admin colors.
  • For frontend screenshots, use the latest WordPress theme.
  • Add the screenshot below the instructions, not above.
  • Use light mode if you’re on macOS, not dark mode.
  • Use a WordPress.com test site and install your extension on it.  Other extensions and plugins might add other tabs or sidebar elements.
  • Ensure that your screenshots and videos are free of unrelated notifications.
  • Avoid censoring information in screenshots. Use a vanilla site with sample data. If you need to highlight multiple orders, create several different orders by multiple users.
  • Use dark purple for annotations created with Droplr. (HEX Code: #6D47C0)
  • Use the latest version of your extension.

Example of a contextual screenshot:

Versus a non-contextual screenshot:

Embrace Diversity

When providing examples in documentation, consider using diverse examples. Instead of using products or names that are only popular in the U.S., choose options that are used in different parts of the world.

Editing Docs

We’re looking for documentation that is:

  • Clear — Straightforward and logical.
  • Consistent — Follows content and formatting guidelines.
  • Empathetic — Anticipates and addresses users’ needs. 
  • Helpful — Ensures users know how to purchase, set up, and maximize use of products.
  • Pithy — Plainest and fewest number of words with appropriate images.

Banned words

  • awesome, best, fastest, greatest, most — All these terms are subjective. Adjectives and marketing copy belong on the product page and not in documentation Marketing = Why. Documentation = How.
  • easy, simple, cakewalk — Disempowers users if they’re unable to follow or understand.
  • extremely, really, very — These modifiers are unncessary.

Emphasis on words in caps (NOT) or italics (must) is avoided.

Formatting

Alphabetize lists, so users can quickly scan.

  • Categories
  • Currency widget
  • Related products
  • Search bar

Arrows — Use > not -> or >>

Box styles 

  • Alert — Urgent warning
  • Info — Fact or explanation
  • Note — Important, non-urgent notice

A bit more details on how to use these can be found below.

Bulleted/Unordered Lists — Use for options and features. Short text lists require no punctuation.

  • Apple
  • Cherries
  • Grapefruit
  • Fruit bowls
  • Picnic baskets
  • Plastic crates and barrels

Longer text lists and complete sentences need a period.

  • Overnight service is available Monday-Saturday for $14.95.
  • Two-day service is available Monday-Friday for $9.95.
  • Three-day service is available Monday-Saturday for $7.95.

Capitalization

  • Bulleted lists — First word only
  • Headings (h2) —Main words, e.g., Setup and Configuration
  • Headings (h3) — First word only
  • Product names — WooCommerce Product Add-Ons

FAQs — Questions use h3. Answers follow in normal text.

Headings — Keep headings brief and relevant. All h2/h3 are auto-assigned anchor links.

  • h2 — Appear in TOC in sidebar
  • h3 — Appear underneath h2 in sidebar

Numbered/Ordered Lists — Use for how-to steps.

Paragraphs — Keep paragraphs brief. Walls of text can intimidate readers.

Parentheses — Avoid parentheses. Practicing a clean and succinct style means all information is important enough to be in normal sentences.

Punctuation — See Grammar, Punctuation, Style.