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

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 meaningfully rename the image. For example, checkout-field-editor-settings or subscriptions-woocommerce-shortcodes.

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.

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 Gardener 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 ->

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.

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