Skip to content

Writing Guidelines

These guidelines govern all user-facing text in the Mukoko ecosystem: UI labels, descriptions, help text, marketing copy, and documentation.

The Mukoko voice is:

  • Clear — say what you mean in the fewest words necessary
  • Warm — friendly without being informal; professional without being cold
  • Empowering — help users accomplish their goals; avoid talking down
  • Grounded — rooted in practical value, not hype

Tone shifts based on context while the voice stays consistent:

Context Tone Example
Success Celebratory, brief “Payment sent successfully”
Error Calm, helpful “We could not process the payment. Check your balance and try again.”
Onboarding Welcoming, guiding “Welcome to mukoko. Let us set up your account.”
Documentation Direct, instructive “Install the component with the shadcn CLI.”
Marketing Confident, inspiring “Built for Africa’s digital future.”

Use sentence case for all UI text — headings, buttons, labels, tabs:

✓ "Getting started"
✗ "Getting Started"
✓ "Add new item"
✗ "Add New Item"

Exceptions: proper nouns (Africa, Zimbabwe) and brand names (mukoko, Nyuchi).

Use active voice. It is more direct and easier to translate:

✓ "You can install components with the shadcn CLI."
✗ "Components can be installed with the shadcn CLI."
✓ "The system saved your changes."
✗ "Your changes have been saved by the system."

Keep sentences under 25 words. Break complex ideas into multiple sentences:

✓ "Components are installed locally. You own the code and can modify it freely."
✗ "Components are installed locally into your project where you own the code and can modify it freely to suit your needs."
  • Use numerals for quantities: “3 components”, “45px touch hit areas”
  • Spell out numbers at the start of sentences: “Five minerals form the palette”
  • Use numerals for technical values: “0.75rem”, “768px”
  • Use the user’s locale format when possible
  • Fallback to day-month-year: “2 April 2026”
  • Use relative time for recent events: “3 hours ago”, “yesterday”

Shona and Ndebele are primary languages in the Mukoko ecosystem, alongside English. Content should be written with translation into these languages in mind from the start. Lingo, a dedicated mukoko mini-app for African language learning, exists as a product — a reminder that language in this ecosystem is not an afterthought but a first-class concern.

Idioms do not translate well and may confuse non-native English speakers:

✓ "Get started quickly"
✗ "Hit the ground running"
✓ "This is easy to use"
✗ "This is a piece of cake"
  • Do not assume Western holidays, seasons, or cultural references
  • Reference shared concepts: seasons differ across Africa (rainy/dry vs four seasons)
  • Use universal metaphors when possible
  • Define technical terms on first use
  • Use consistent terminology — pick one term and use it everywhere
  • Avoid unnecessary jargon: “set up” not “bootstrap”, “install” not “scaffold”

Use action verbs that describe what happens:

✓ "Save changes" ✗ "Submit"
✓ "Delete account" ✗ "Remove"
✓ "Send message" ✗ "OK"

Be specific and concise:

✓ "Email address" ✗ "Email"
✓ "Full name" ✗ "Name"
✓ "Phone number" ✗ "Phone"

Tell users what they can do, not just what is missing:

✓ "No messages yet. Start a conversation to see messages here."
✗ "No data found."

State what will happen and whether it can be undone:

Title: "Delete this item?"
Body: "This will permanently delete the item and all associated data. This action cannot be undone."
Actions: "Delete item" / "Cancel"