Release 0.3.0-draft.1 · Development standards
Sound like a capable person explaining useful work. Clarity should survive when the subject is complex or the news is difficult.
Voice that changes with the reader's situation
| Situation | Tone | Draft example |
|---|---|---|
| First encounter | Confident, inviting | Make room for better work. Start with one useful workflow. |
| Explaining a service | Specific, grounded | We start with the tools and recurring tasks your team already uses. |
| Explaining AI | Clear about scope | The tool prepares a draft. Your team checks it before sending. |
| Asking for details | Respectful, purposeful | Tell us which part of the work keeps getting stuck. |
| Error | Calm, useful | Your request could not be saved. Check your connection and try again. |
| Confirmed saved request | Factual | Your request has been saved. We’ll be in touch to arrange a conversation. |
| Difficult update | Direct, accountable | We found a problem in the handoff. We have paused it while we check the affected records. |
These examples are copy patterns. Use success or recovery wording only when the actual behaviour supports it; do not promise that input is retained without verification.
Editing examples
| Avoid | Prefer | Why |
|---|---|---|
| Unlock revolutionary AI-powered transformation | Find one workflow worth improving | Concrete scope |
| Every enquiry answered instantly | Prepare enquiry replies for your team to review | No unsupported guarantee |
| Our intelligent agent handles everything | The agent prepares suggestions; you choose what to use | Visible responsibility |
| Your meeting is booked! | Your call request has been saved | Matches the event |
| Oops! Something went wrong | We couldn’t save your changes. Try again | Names the failure and action |
| Seamless integration with all your systems | We’ll check how your current tools can connect | Leaves room for actual constraints |
Writing conventions
Use South African English: organisation, prioritise, colour. Use natural contractions where they aid reading. Keep headings in sentence case and buttons as short verb phrases: “Explore services”, “Request a conversation”, “Download the guide”. Use “click” only for mouse-specific instructions; otherwise “select”, “open” or the control label.
Write user-facing dates as “13 October 2026” and include Africa/Johannesburg or SAST when schedule ambiguity matters. Use YYYY-MM-DD in filenames. For local currency, write “R1,250” and make VAT/inclusions explicit when known; use “ZAR” in international or mixed-currency tables. Never infer a price. Spell out a term before its abbreviation. Prefer “AI” over repeatedly spelling out artificial intelligence when the audience already understands it.
Headings should make sense when read alone. Links should name the destination or action, not “click here”. Avoid idioms that depend on one cultural background, unexplained acronyms and jokes in errors. Alt text explains useful visual information; it does not repeat marketing slogans.
Ready-to-adapt patterns
Social: “Which follow-up keeps slipping? A useful workflow starts with one recurring task, a clear owner and a review point. Explore Woblar’s services.”
Proposal opening: “You described [verified problem]. We propose starting with [bounded workflow], using [confirmed tools]. [Role] will review [output] before [action]. Success will be assessed against [agreed measure].”
Case study: situation → agreed scope → delivered work → measured outcome and period → limitations → next step. If the outcome is not measured, describe the delivered capability and leave the result unclaimed.
Operating rules
COPY-001 — Support claims
- Do: Attach a current source to performance, customer and comparative claims.
- When: Copy, campaigns and sales
- Variation: Describe bounded capabilities or label illustrative examples.
- Avoid: Invented savings, testimonials, endorsements or guaranteed outcomes.
- Check: Review a claim ledger containing source, date, permission and scope.
COPY-002 — Write for a decision
- Do: Use a concrete subject, active verb and useful next action.
- When: Headings, body copy and CTAs
- Variation: More expressive headlines when a nearby descriptor explains the offer.
- Avoid: Hype, jargon, false urgency or vague CTA labels.
- Check: Read headings and actions alone; their purpose remains clear.
COPY-003 — Match the emotional moment
- Do: Use calm factual language for errors and honest accountability for delays.
- When: Status, support and difficult updates
- Variation: Warm contractions in ordinary conversation.
- Avoid: Blame, jokes at a point of failure or unsupported reassurance.
- Check: Compare wording with the reader’s situation and known facts.