Writing Documentation

Writing clear and thorough documentation demonstrates your commitment to merchant success and sets expectations for the quality of your product and support. This style guide helps ensure a unified, consistent experience across WooCommerce.com, providing users with documentation that’s informative, educational, and empowering so they can confidently get the most out of your product.

When writing documentation, strive for technical writing that is:

• Clear – Straightforward and logical.
• Consistent – Follows the content and formatting guidelines.
• Empathetic – Understands and addresses our audience.
• Helpful – Provides information that users need to know to purchase, set up, and maximize the use of the product.
• Direct – Plainest and fewest number of words with appropriate images.
• Friendly – The voice and tone is conversational, friendly, and global. The writing style is clean and lean, following our guide for Grammar, Punctuation and Capitalization.

We offer two types of documentation ― one for all users and one for our developer community with more technical experience.

1. Organize ― Think about your audience, gather notes, and make an outline. Know your outcome.
2. Draft ― Use the templates provided and complete each relevant heading.
   • Payment Gateway Docs Template – Examples: Amazon Pay, GoCardless, Payfast, Payment Express, PayPal Advanced.
   • Extension/Add-On Docs Template – Examples: WooCommerce Box Office, WooCommerce Memberships, Product Add-Ons, Accommodation Add-On for Bookings.

We also have Use Cases, Tables and Comparisons to assist users in setup or selection of the appropriate product.

3. Add images ― Use Droplr, CleanShot X ,or a similar application to take high-quality screenshots, annotate as needed with arrows and boxes, and meaningfully rename the image. Make sure your screenshots and videos match your written documentation exactly. See our full Image Guidelines for more details
4. Review ― Review the Formatting section below, and the Grammar, Punctuation, Style page, adjust where necessary.
5. Proofread for typos and incorrect word usage.

For user documentation, keep in mind you’re writing for a non-technical audience. Here are a few tips that can help:

• Explain as though the user has zero experience with WooCommerce and your extension.
• List every single step. One missing step in the process can result in a user not being able to follow the instructions.
• Also, use a new step for each separate action.
• Use bold print to highlight:
  • The verb — ideally, an imperative — or the main focus of each step
  • The path — e.g. WooCommerce > Settings
• Test your documentation by having a new user set up the product. Were they able to work through the documentation without trouble? 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 WooCommerce Support Policy explicitly says that customization is beyond the scope of support we provide. Deciding to include them in your docs is a long-term choice you need to make on your own regarding support, maintenance, troubleshooting and managing customer expectations.

A good screenshot in the right place can significantly improve product documentation.

Screenshot guidelines

• Remember that images should be optional. Make sure that you write out any instructions in the accompanying text. For visitors who use screen readers, it would be a challenge to follow instructions that are only given via a screenshot.
• Use the Modern WordPress admin color scheme.
  
• For frontend screenshots, use Storefront as the theme, unless you’re documenting a different theme. 
• Add the screenshot below the written instructions, not above. 
• Use light mode when taking screenshots, not dark mode. 
• Use a test site that only has WooCommerce Core and the extension you are documenting installed. Other extensions and plugins might add other confounding tabs, settings, or sidebar elements.
• Make sure no unnecessary notifications are showing. 
• Avoid needing to censor information in screenshots. Ideally, use a testing site with sample data. If you need to highlight orders, create several orders by multiple test users.
  • You can also avoid the need to censor information by editing the page HTML using your browser’s developer tools (i.e., right-click, inspect element, and manually edit the HTML to remove sensitive or personal information.)
• If you annotate the screenshot using a screenshot editing tool, use a high contrast red color for annotations. We use a bright red with hex code #F93442.
• If your images are more narrow than the content column (653px), center them.
• Always use the latest version of WordPress Core, WooCommerce Core, and your extension(s).
• Take a contextual screenshot for the first screenshot that moves the user to a new path. E.g., when going from a different section to WooCommerce  > Settings > Payments, include the sidebar in the screenshot to help the user navigate. 

Give readers enough visual information to locate where they are in the interface, but not so much that the focus of your screenshot is unclear. Screenshots of the full admin area are not usually necessary unless you’re illustrating how to navigate to the item in question.

In-product screenshots should be lightboxed

All screenshots that demonstrate the in-product experience you’re documenting should be lightboxed. So that users can expand them with a click to see more details as needed. WooCommerce.com has a custom lightbox functionality that works with the “Link to image file” option.

To lightbox an image in your documentation, use the “Link to image file” option in the block toolbar. 

Images in docs must be uploaded to the WooCommerce.com media library

Images are not auto-uploaded to the WooCommerce.com media library when content is copied and pasted from a Google Doc etc. into the block editor. This can leave the images in your document hosted externally and referenced by URL in the doc content. If the external reference isn’t public (e.g. Google Docs storage is often not publicly accessible), then it will lead to the image showing as broken when the page is viewed by someone outside your organization. 

This is pernicious because you won’t notice the broken image unless you view the page in a private browsing session. 

You can spot an external image by the additional button that will show in the block toolbar when you select it, click this “Upload to media library” button to pull the file into the media library on WooCommerce.com, solving the problem.

Placing images between items in ordered lists

When working with an ordered (i.e., numbered) list, you’ll find additional options in the block settings sidebar.

You can select the “Start value” setting to set your list to begin from a number other than 1. This option is useful if you need to insert non-text content (like an image) between items in your list, then continue the numeric list below.

This ensures that the next item in the list after the image contains the next number in the sequence. This is important for our AI systems to correctly understand the sequence of steps that you’re sharing.

Here’s where you’ll find the setting, be sure you have the list element selected and not a list item:

Annotations & Highlights

Annotations are useful to point out important specifics in screenshots. However, images should only show one process or completed settings configuration. If a process is more than three steps, consider breaking it into two or more images.

Make sure any annotations you add:

• Use a high contrast red color. We use a bright red with hex code #F93442
• Are numbered if necessary
• Are easy for users of all types to understand

If you want to highlight or spotlight content, consider using Apple’s built-in screenshot editor (preview) or CleanShot-X, which has a similar feature.

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.

If you are using the block editor for your docs — which we highly recommend — consider using some of the synced patterns. You can review all available patterns here. You can insert reusable patterns by name using the slash inserter when working in the block editor.

These can be used for:

• Support instructions
• Support scope notices when providing developer level information
• Etc.

One big advantage is that when we update a synced pattern due to a change in instructions, they are updated everywhere.

The table of contents in the left sidebar are auto generated based off the content of H2 and H3 level headings. These headings are linked to by their anchor links.

When an specific anchor link is not manually specified, the system automatically generates a #section-N anchor link that gets automatically numbered based on the position of the heading in the document.

This system works by auto-populating an anchor link value based on the heading title and prepending h- to it. i.e. h-table-of-contents-and-anchor-links for this section. If the h- isn’t removed from this default, a #section-N anchor will be added programmatically and used.

We recommend to remove the h- prefix from the auto-generated anchor link so that an anchor based on your heading title is set. Ideally, finesse the anchor link slug to prevent it being repetitive or unclear.

To do so, select the Heading block and view the Block settings under the Advanced section. There you’ll find a field to edit the HTML anchor. Here are the syntax requirements copied from the WordPress.org Page Jumps document.

• HTML Anchors must be unique within a document.
• HTML Anchors are case-sensitive. We recommend using all lowercase anchors.
• HTML Anchors can include following symbols: hyphen(-), underscore(_), colon(:), period(.). It cannot include spaces.
• HTML Anchors must start in the alphabet.

Alphabetize lists, so users can quickly scan.

• Categories
• Currency widget
• Related products
• Search bar

Arrows – Use a single bolded right angle bracket > not -> or >>

Capitalization

• Bulleted lists – First word only
• Headings (h2) – Use title case. Capitalize main words, e.g., Setup and Configuration
• Headings (h3) – Use sentence case. Capitalize the 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 headings are auto-assigned anchor links. H2 and H3 will appear in the left sidebar navigation menu.

• h2 – Appear in TOC in sidebar
• h3 – Appear underneath h2 items in sidebar

Lists – Any time you find yourself using serial commas, consider whether to convert the content to a list.

Numbered/Ordered Lists – If rearranging the list items would change the list’s meaning, use an ordered list.

Bulleted/Unordered Lists – If the list items could be rearranged without changing the list’s meaning, use an unordered list.

Short list items need no punctuation.

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

Longer text lists and complete sentences need a period.

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

Paragraphs – Keep paragraphs brief. Walls of text are heavy and intimidating.

Parentheses – Avoid parentheses when possible. Practicing a clean and lean writing style means all info should be important enough to present in normal sentences.

Punctuation – See our Grammar, Punctuation and Style guide in our developer documentation. The same guidelines apply to merchant documentation on WooCommerce.com.

Editing documentation upon changes or updates to your extension is essential to ensuring users can easily manage their plugins. Plan time to update your documentation text and images when changes or new features happen in your extension.

WooCommerce.com uses PublishPress Revisions to enable new versions to be created before they go live. This way, you can safely edit content on published documentation while preparing for changes.

To create a new revision in a document, click the New Revision button in the documentation sidebar. Once a new revision is generated, Preview or Edit it from the available buttons.

Your vendor dashboard includes a menu for your revisions queue. Here, you can easily access and manage created revisions. From here, you can edit, preview, or compare the revisions.

While editing the revision, it will be in draft state. Click the current status to update it. Keep it as a draft, schedule the revision for a later date, or publish it when ready. Click the Publish date to select the schedule date. If you select “Pending,” be sure that you or a member of your team reviews the queue to publish or schedule the revision.

Previewing revisions provides access to compare, view the original, edit the revision, submit for your team to review, or publish.