Writing style guide

This expanded style guide formalises the content, structure, tone, and formatting rules for all ShopWired help documentation and UI copy. It is designed for daily use by writers and editors, providing detailed, example-rich guidance for every aspect of ShopWired content creation. All examples are real or representative of current ShopWired content.

---

Rationale:
A consistent, formal, and instructional tone ensures users receive clear, trustworthy, and actionable information. This helps users complete tasks efficiently and builds confidence in ShopWired’s documentation.

Usage Rules:

• Use a formal, professional, and instructional tone
• Avoid casual, conversational, or overly friendly language
• Do not use exclamation marks for emphasis (except in markdown for formatting)
• Avoid words like “quick”, “easy”, “simple”, “great way”
• Do not use “we”, “our”, or company-centric language unless describing ShopWired’s actions or policies
• Focus on what the user can do, not what ShopWired does

Examples:

• Don’t: “It’s easy to add a product to your store!”

• Do: “To add a product, navigate to Products > Create product.”

• Don’t: “We recommend you check your settings.”

• Do: “Check your settings to ensure they are correct.”

• Don’t: “You’ll love how simple this is!”

• Do: “Follow the steps below to complete the process.”

Edge Cases:

• When referencing ShopWired’s own actions (e.g. “ShopWired will send you an email”), use third-person or passive constructions
• If a user’s action is not possible, state the limitation directly: “This feature is not available on ShopWired.”

---

Rationale:
Clear, concise sentences in active voice make instructions easier to follow and reduce ambiguity.

Usage Rules:

• Use active voice: “Select the edit link to edit the product.”
• Keep sentences concise; one idea per sentence
• Use imperative verbs for instructions: “Navigate to...”, “Select...”, “Enter...”
• Avoid filler words: “please”, “you can”, “we recommend”, “simply”, “just”
• No idioms or slang; use literal, plain English
• No unnecessary apologies; focus on solutions, not blame

Examples:

• Don’t: “You can click here to learn more.”

• Do: “Read more about product settings.”

• Don’t: “Please remember to update your settings.”

• Do: “Update your settings.”

• Don’t: “If you want, you can just click the button.”

• Do: “Select the button.”

Edge Cases:

• When a step requires context, use a short introductory sentence before the instruction
• For error messages, state the problem and solution in one sentence: “Enter a valid email address.”

---

Rationale:
Consistent capitalisation and punctuation improve readability and maintain a professional appearance.

Usage Rules:

• Use sentence case for all headings, button labels, menu items, and field labels (only the first word and proper nouns are capitalised)
• Do not use all-caps for emphasis or branding
• Do not capitalise for emphasis
• End punctuation:
  • Sentences in body text and notices end with a full stop
  • Sentences in bullet points and numbered lists do not end with a full stop
  • Headings, subheadings, button labels, and menu items do not have end punctuation

Examples:

• Don’t: “CREATE PRODUCT”

• Do: “Create product”

• Don’t: “Welcome to your store.”

• Do: “Welcome to your store”

• Don’t: “Product settings.”

• Do: “Product settings”

Edge Cases:

• If a heading includes a proper noun, capitalise only the proper noun: “Using Google Analytics”
• For acronyms, use standard capitalisation: “VAT settings”

---

Rationale:
Consistent heading structure and formatting help users scan and navigate content efficiently.

Usage Rules:

• h1: Reserved for article titles (set automatically). Do not use in public help guides.
• h2: Used for major sections. Each h2 creates a sidebar menu entry.
• h3: Used for sub-sections, FAQs, troubleshooting, use cases, or as sub-headings within lists.
• h4: Rarely used; only for further sub-division within h3 sections.
• h5: Used for setting names or column headings in settings documentation.
• h6: Reserved for code variables (e.g. Twig variable names).
• Do not bold headings.
• Do not use italics.

Examples:

Edge Cases:

• Use h4 sparingly and only within AI content for further sub-division
• Never use bold or italics in headings

---

Rationale:
Clear, action-oriented buttons and CTAs help users understand what will happen when they interact with the UI.

Usage Rules:

• Start with a strong verb: “Add product”, “Save changes”, “Delete”, “Install this app”
• Keep it short: 1–3 words
• Use sentence case
• No “please”, “now”, or “click here”

Examples:

• Don’t: “You can add apps”

• Do: “Add apps”

• Don’t: “Submit now”

• Do: “Submit”

Rationale:
Descriptive, concise headings help users find information quickly.

Usage Rules:

• Be descriptive and concise: “Order status emails”, “Configuring product choices”
• No end punctuation
• No unnecessary words: Omit “This is”, “Your”, “Our”

Examples:

• Don’t: “This is your online store dashboard”
• Do: “Online store dashboard”

Rationale:
Clear, short labels and helper text reduce user confusion and errors.

Usage Rules:

• Short, descriptive, and in sentence case: “First name”, “Email address”
• Optional fields: Indicate with “(optional)” in lowercase
• Helper text: Use neutral, instructive tone

Examples:

• “Apartment, suite, etc. (optional)”
• “Search by name or SKU”

Rationale:
Actionable, specific error messages help users resolve issues quickly.

Usage Rules:

• State the problem and solution: “Enter a valid email address.”
• Be specific: “Title is too long (max 70 characters).”
• No jargon: Avoid “invalid” or technical codes
• No blame or “we/our” unless ShopWired is at fault

Examples:

• Don’t: “Invalid title.”
• Do: “Enter a title for the product and try again.”

Edge Cases:

• If a technical code must be included, explain it in plain language: “Payment failed (error code 123). Please try again.”

---

Rationale:
Consistent terminology ensures users understand features and reduces confusion.

Usage Rules:

• Use ShopWired’s defined terms: “Visitor”, “Customer”, “User”, “Website”, “Setting”, “Option”
• Be consistent: Use the same term for the same concept throughout
• Use descriptive, not branded, names: “Order editing”, not “OrderWizard”
• Refer to UI elements exactly as they appear: Use the exact label from the interface
• Avoid internal code names or acronyms: Use customer-facing names only

Examples:

• Don’t: “Use our e-commerce platform to run your business.”

• Do: “Run your business using ShopWired.”

• Don’t: “Click the ‘magic button’.”

• Do: “Select the Save changes button.”

Edge Cases:

• If a UI label changes, update all references in documentation to match

---

Rationale:
Inclusive language ensures all users feel welcome and can access information equally.

Usage Rules:

• No gendered language: Use “they” or “you” instead of “he/she”
• No idioms, metaphors, or culturally specific references
• No insensitive or exclusionary terms: Use “disability” not “handicap”, “allow list” not “whitelist”
• Use plain, literal language

Examples:

• Don’t: “Whitelist this user.”

• Do: “Add this user to the allow list.”

• Don’t: “He should update his settings.”

• Do: “Update your settings.”

Edge Cases:

• If a term is industry-standard but potentially exclusionary, provide a plain-language explanation or alternative

---

Rationale:
Descriptive, consistent links improve navigation, accessibility, and SEO.

Usage Rules:

• Descriptive anchor text: “Learn more about delivery rates”, not “click here”
• No bold links except for ShopWired UI links
• Links to other help guides: Open in the same window
• Links to ShopWired’s website, account pages, or external sites: Open in a new window (add ! at the end)
• No punctuation inside links
• Use bold only for UI navigation links:
  Navigate to **[Dashboard > Reports](https://admin.myshopwired.uk/business/manage-ecommerce-reports)!**

Examples:

• Don’t: “For more information, [click here].”

• Do: “Read more about product settings.”

• Do:

  Navigate to **[Dashboard > Reports](https://admin.myshopwired.uk/business/manage-ecommerce-reports)!**

Edge Cases:

• If a link is both a UI navigation and an external link, use both bold and ! at the end

---

Rationale:
Consistent list and table formatting improves readability and supports ShopWired’s markdown rendering.

Usage Rules:

• Tables: Use standard markdown, no extra spaces
• Numbered lists: For instructions only
• Bullet points: For all other lists
• Nested bullets: Use -- for secondary bullets
• No tertiary indentation

Examples:

Edge Cases:

• If a list item contains a full sentence, do not add a full stop at the end

---

Rationale:
Strict formatting rules ensure clarity and prevent misuse of emphasis.

Usage Rules:

• Bold: Only for setting names and section names within text, numbered lists, and bullet points
• Italics: Never used
• Backticks: For code, variable names, and column headings
• No bold in headings
• No bold links except for UI links

Examples:

• “Select yes from the Setting name setting.”
• “To return the title of the product use the Twig variable product.title.”

Edge Cases:

• If a setting name is also a link, use bold for the setting name and follow link rules

---

---

• Before: “It’s not possible to proceed at this time.”
• After: “You cannot proceed right now.”

• Before: “Do not forget to update the settings.”
• After: “Update the settings.”

• Before: “Create Purchase Order”

• After: “Create purchase order”

• Before: “Sell your products in person!”

• After: “Sell your products in person”

• Before: “You can add apps”

• After: “Add apps”

• Before: “Duplicate this order so that you can make edits…”

• After: “Duplicate”

• Before: “Invalid title.”
• After: “Enter a title for the product and try again.”

• Before: “For more information, [click here].”
• After: “Read more about product settings.”

• Before:
  Use Shopify Payments to avoid the hassle of setting up a gateway, track pending payout schedule, minimize lost sales from chargebacks. And eliminate PCI fees
• After:
  Using Shopify Payments in your store provides the following benefits: - Avoids the hassle of setting up a third-party payment gateway - Tracks your payout schedule from the Shopify admin - Minimises lost sales from chargebacks

---

---

Rationale:
ShopWired’s markdown and content system has unique requirements for formatting, notices, and media.

Usage Rules:

• Markdown: All content must be written in ShopWired’s adapted markdown, following the markdown style guide
• Notices: Use HINT:, CAUTION:, and WARNING: for callouts
• Images: Use standard markdown, with optional width and zoom indicator
• Videos: Use IFRAME: or [view video](...) as specified
• Tables: No extra spaces, no unnecessary delimiters
• Links: Use ! at the end for new window where required
• No italics: Italics are not used anywhere
• No all-caps: Never use all-caps for emphasis or branding
• No bold in headings: Headings must not be bolded
• No punctuation in headings: Do not end headings with punctuation

Examples:

---

Rationale:
Accessible content ensures all users, including those with disabilities, can use ShopWired’s documentation and UI.

Usage Rules:

• Alt text: All images must have descriptive alt text
• No gendered or exclusionary language
• No idioms, metaphors, or culturally specific references
• Plain, literal language

Examples:

• Don’t: “Whitelist this user.”

• Do: “Add this user to the allow list.”

• Don’t: “He should update his settings.”

• Do: “Update your settings.”

---

Rationale:
Standardised patterns make content predictable and easy to use.

Usage Rules:

• Instructions: Use numbered lists, one action per step
• Settings: Use h5 for setting names, with bold for setting names in text
• FAQs: Use h3 for each question
• Troubleshooting: Use h3 for each issue
• Use cases: Use h3 for each use case
• Workarounds: Use h3 for each workaround

Examples:

---

• Is the tone formal, professional, and instructional?
• Are sentences concise and in active voice?
• Are headings in sentence case, with no bold or punctuation?
• Are UI elements and settings named exactly as in the interface?
• Are lists and tables formatted according to ShopWired markdown rules?
• Are links descriptive and formatted correctly?
• Is bold used only for setting/section names?
• Are error messages clear, actionable, and jargon-free?
• Is language inclusive and accessible?
• Are all images and videos formatted per ShopWired rules?
• Is all content in ShopWired markdown?

---

By following this style guide, all ShopWired help documentation and UI copy will be clear, consistent, and user-focused, supporting users in successfully managing their ecommerce websites.

---

Bullet List with Indented Sub-Bullets:

Numbered Steps with ShopWired-Style Formatting:

Bold and Backtick Use in Paragraphs:

Setting Name in h5:

Twig Variable in h6:

---

• When rules conflict (e.g. a setting name is also a link), use bold for the setting name and follow link rules for the link
• If a list item is a full sentence, do not add a full stop at the end
• If a UI label changes, update all references in documentation to match
• For technical codes in error messages, explain in plain language

---

For further details on markdown formatting, refer to the ShopWired markdown style guide.