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
- 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.
- 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.
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.
- Currency widget
- Related products
- Search bar
Arrows — Use > not ->
- 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.
- 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.