Writing Documentation

Mission of Docs ↑ Back to top

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

How a Style Guide Supports Docs ↑ Back to top

  • Provides consistent presentation and experience for users
  • Creates a unified voice for multiple authors
  • Saves time and resources by having decisions in place

Voice and Tone ↑ Back to top

  • Conversational, friendly, and global

Writing Style ↑ Back to top

  • Clean and lean

Types of Docs ↑ Back to top

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

User ↑ Back to top

  • Setup and Configuration
  • Use Cases
  • Comparisons
  • Video Tutorials

Developer ↑ Back to top

  • Hooks and Filters
  • Function Reference
  • Code Snippets
  • API

Writing Docs ↑ Back to top

A general overview to crafting product documentation.

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

Draft — Use the templates provided and complete each relevant heading.

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

Add images — Use Droplr or a similar application to take high-quality screenshots, annotate with blue arrows and boxes, and meaningfully rename the image. For example, checkout-field-editor-settings or subscriptions-woocommerce-shortcodes. Make sure your screenshots and videos match your written documentation exactly.

Review — Review the Formatting section below, and the Grammar, Punctuation, Style page (add link), and adjust where necessary.

Proofread for typos and incorrect word usage.

For user documentation, keep in mind you’re writing for a non-technical audience. Explain as though the user has zero experience with WooCommerce and your extension. 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.

Editing Docs ↑ Back to top

Our WooCommerce Docs Lead blind-tests the extension/payment gateway/add-on from installation to going live, verifying accuracy of text and images at every step. Context and/or detail is added, word count is cut to bare minimum, and then the page is previewed, tweaked and finalized.

We’re looking for documentation that is:

  • Clear — Straightforward and logical.
  • Consistent — Follows content and formatting guidelines.
  • Empathetic — Understands and addresses our audience.
  • Helpful — Provides information that users need to know to purchase, set up and maximize use of products.
  • Pithy — Plainest and fewest number of words with appropriate images.

Banned words ↑ Back to top

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

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

Formatting ↑ Back to top

(*Add screenshots to differentiate text from examples?)

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

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.


  • 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 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 brief. Walls of text are heavy and intimidating.

Parentheses — Avoid. Practicing clean and lean style means all info is important enough to be in normal sentences.

Punctuation — See Grammar, Punctuation, Style.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top