Style Guide

Consistency is credibility. This style guide defines how KMS articles should read, look, and feel — from voice and tone to formatting and naming conventions.

Voice and Tone

Voice: Professional, Direct, Helpful

The KMS voice is:

Professional but not academic — Write like a trusted colleague briefing a peer, not a lecturer addressing a lecture hall. Use plain English. Avoid jargon unless it's domain-essential and defined.
Direct but not abrupt — Get to the point. Lead with the conclusion or recommendation, then provide context. Readers scan before they read.
Helpful but not patronising — Assume competence. Explain why, not just what. Don't over-explain basic concepts.

Tone by Content Type

Tone shifts slightly depending on the content type:

Content Type	Tone
Briefing Note	Concise, action-oriented, authoritative
Research Report	Analytical, measured, evidence-based
How-To Guide	Encouraging, instructional, step-by-step
Policy Analysis	Objective, balanced, forward-looking
Case Study	Narrative, confident, outcome-focused
Reference Material	Neutral, precise, comprehensive
Template	Instructional, clear, adaptable
Training Resource	Supportive, structured, pedagogically sound

Voice Comparison

Too academic: "It is imperative that stakeholders undertake a comprehensive analysis of the regulatory framework prior to the commencement of engagement activities."
Too casual: "You gotta check the rules before you start talking to anyone, obviously."
KMS voice: "Analyse the regulatory framework before engaging stakeholders. Understand what's changing, who it affects, and what it means for your client."

Language Conventions

Australian English

Use Australian English spelling throughout:

✅ organisation (not organization)
✅ colour (not color)
✅ analyse (not analyze)
✅ centre (not center)
✅ defence (not defense)
✅ labour (not labor)
✅ licence (noun) / license (verb)
✅ practise (verb) / practice (noun)
✅ programme (not program, except for computer programs)

Capitalisation

Sentence case for titles and headings. Capitalise only the first word and proper nouns:

✅ "SA State Budget 2026-27 — Health Portfolio Analysis"
❌ "SA State Budget 2026-27 — Health Portfolio Analysis" (every word capitalised)
✅ "Key findings from the April poll"
❌ "Key Findings from the April Poll"

Proper nouns are capitalised:

Organisations: SA Health, DemosAU, Aspen Medical, Ace Strategies
People: Matt Neagle, Andrew Parnell
Places: South Australia, Adelaide, Greater Adelaide
Legislation: Health Performance Council Act 2024
Programs: My Health Record, SA Tenders and Contracts

Job titles — capitalise when referring to a specific person's title, lowercase when generic:

"the Secretary of SA Health"
"a departmental secretary"

Numbers

Spell out numbers one to nine. Use digits for 10 and above
Use digits for all numbers in tables, regardless of size
Use commas for thousands: 1,247 (not 1247)
Percentages: use the % symbol (not "percent"), no space: 47% (not 47 %)
Currency: $47 million, $2.4M (short form in tables), A$8.2 billion (first mention in body text; subsequent mentions can use $)
Dates: 19 June 2026 (not June 19, 2026 or 19/06/2026)

Abbreviations

Spell out on first use: "Foreign Investment Review Board (FIRB)"
Use the abbreviation consistently after first definition
Common abbreviations that don't need expansion: SA (South Australia), NSW, UK, US, EU, MP, CEO
Don't abbreviate for brevity alone — only if the abbreviation is widely recognised

Punctuation

Oxford comma: Use it. "government relations, stakeholder engagement, and strategic communications" (not "government relations, stakeholder engagement and strategic communications")
Em dashes: Use spaced en dashes for parenthetical content — like this — not hyphens
Quotation marks: Single quotes for inline quotes ('like this'), double quotes only for quotes within quotes
Ampersands: Use only in proper names (Health & Ageing) and navigation labels. Spell out "and" in body text.

Read It Aloud

If a sentence is hard to read aloud, it's hard to read silently. Break it into two. If a paragraph fills more than five lines on screen, split it. Short sentences are not a sign of simple thinking — they're a sign of clear thinking.

Article Structure

The Inverted Pyramid

Structure every article so the most important information comes first:

Title — What the article is about, in one line
Excerpt — The one-sentence value proposition: why should someone read this?
First paragraph — The conclusion, recommendation, or key finding. Don't bury the lead.
Supporting sections — Evidence, analysis, context, methodology
Next steps / recommendations — What the reader should do with this information

A reader who stops after the first paragraph should still get the main point.

Headings

H2 for major sections. Every H2 should be a self-contained topic.
H3 for subsections within an H2. Don't skip from H2 to H4.
H4+ — Available but rarely needed. Consider splitting the article if you need deep heading nesting.
Heading text — Use sentence case. Make headings descriptive, not clever. "Key Budget Measures" not "Where the Money Goes".
Heading length — Aim for 3-8 words. A heading that wraps to two lines is too long.

Paragraphs

One idea per paragraph. If you change topic, start a new paragraph.
Opening sentence carries the paragraph's main point. Subsequent sentences elaborate.
Length — 2-5 sentences. A paragraph longer than five lines on screen signals that the idea needs breaking up.
Transitions — Connect paragraphs with logical flow. The last sentence of one paragraph should set up the first sentence of the next.

Lists

Use bullet lists for:

Unordered items where sequence doesn't matter
Key points, implications, or recommendations
Checklist items

Use numbered lists for:

Sequential steps in a process
Prioritised recommendations (1 = highest priority)
Ranked items

List Length

A list with more than 8 items is hard to scan. Group long lists into categories, or convert to a table.

Tables

Use tables for comparing parallel data points. A good table:

Has a header row that labels each column
Is readable at 320px width (test on mobile)
Uses consistent formatting (numbers right-aligned, text left-aligned)
Includes units in column headers, not in every cell (e.g., "Budget ($M)" not "$47M per cell")

| Stakeholder | Position | Priority |
|------------|----------|----------|
| SA Health | Supportive | High |
| Opposition | Cautious | Medium |
| AMA (SA) | Supportive | Medium |

Callout Conventions

Callouts are the KMS's most distinctive formatting feature. Use them deliberately.

Callout Types and Their Purposes

Callout	Use For	Example
`note`	Supplementary information, context, sources	"Budget figures sourced from SA Government Budget Paper 3."
`tip`	Best practices, shortcuts, efficiency suggestions	"Use raw Markdown mode for tables and callouts."
`warning`	Risks, pitfalls, things that could go wrong	"Deleting an article removes it permanently from the repository."
`important`	Critical information that must not be missed	"The status field controls whether your article is visible on the live site."
`info`	Contextual background, "did you know" content	"Sveltia CMS commits changes directly to the GitHub repository."
`success`	Positive outcomes, achievements, confirmations	"You've created and published your first KMS article."
`question` / `faq`	Frequently asked questions, common queries	"Can I skip the review stage?"
`example`	Illustrative content, demonstrations	"Here's how the same information reads in KMS voice versus academic voice."
`quote` / `cite`	Client testimonials, external quotations	"Ace Strategies helped us strengthen our relationship..."
`abstract` / `summary` / `tldr`	Article summaries, key takeaways	Use at the top of long articles for time-pressed readers.

Callout Rules

One callout per 300 words — More than that and they lose impact. The reader stops noticing them.
Don't nest callouts — A callout inside a callout renders unpredictably.
Include a title — Every callout should have a title line (> [!type] Title Here). Untitled callouts look like formatting errors.
Match type to purpose — A warning callout for routine information creates false alarm. A tip for critical safety information understates the risk.
Place after the relevant content — Callouts expand on what the reader just read. Don't use them to introduce new topics.

Callout Title Convention

Callout titles use Title Case — capitalise the first letter of each major word. Keep titles short: 2-4 words. "How to Publish" not "Here Is How You Can Publish Your Article".

Naming Conventions

Article Titles

Sentence case — "SA State Budget 2026-27 — Health Portfolio Analysis"
Descriptive, not clever — The title should tell the reader exactly what they'll learn
No colons in titles — Use an em dash (—) to separate a topic from its descriptor. "Key Budget Measures — Telehealth Expansion" not "Key Budget Measures: Telehealth Expansion"
Unique — Don't use the same title as an existing article. Check the knowledge base index first.

File Names

Article slug is derived from the filename: write-your-first-article.md → /staff/knowledge/write-your-first-article/
Lowercase, hyphen-separated, no special characters
Match the title closely — The filename should be a URL-safe version of the title
Keep it under 60 characters — Long slugs are hard to read and share

Image File Names

Descriptive: sa-health-budget-briefing-hero.webp (not IMG_4728.webp)
Lowercase, hyphen-separated, no spaces
Include context: what the image shows, not where it came from
Format extension: use .webp for photos, .svg for logos and icons, .png for screenshots

Formatting Reference

Bold and Italic

Bold for strong emphasis and key terms on first use: "The status field controls visibility."
Italic for titles of publications, legislation, and reports: SA Government Budget Paper 3
Don't combine bold and italic. Don't use bold for entire sentences.

Code and Technical Content

Use inline code (backticks) for: field names (status), file paths (src/content/knowledge/), commands (npm start), and YAML values (published)
Use code blocks (triple backticks) for multi-line content: front matter examples, configuration snippets, data samples
Specify the language for syntax highlighting: ```yaml, ```markdown

Images

Every image must have alt text — descriptive, in sentence case, ending without a full stop
Hero images: 1200×630px for optimal Open Graph rendering
In-body images: content-width (780px max). Larger images are automatically constrained by the CSS
File format: WebP preferred for photos (smaller, faster). PNG for screenshots with text
Caption via image_alt — The image_alt field displays as a figure caption below the image

Quality Checklist

Before publishing any article, verify:

Front Matter

[ ] status is set correctly (draft for in-progress, published for live)
[ ] title uses sentence case
[ ] category matches the article's primary subject
[ ] excerpt is one sentence, under 160 characters
[ ] tags_list has 2-6 lowercase, hyphen-separated tags
[ ] last_updated is current (for revisions)

Structure

[ ] H2 headings mark major sections; H3 for subsections within each H2
[ ] First paragraph communicates the main point (inverted pyramid)
[ ] Paragraphs are 2-5 sentences each
[ ] Lists and tables are used where appropriate
[ ] Article has a clear next step or call to action at the end

Language

[ ] Australian English spelling throughout
[ ] Sentence case for headings
[ ] Numbers formatted correctly (commas, % symbol, currency)
[ ] Abbreviations defined on first use
[ ] Jargon explained or avoided

Formatting

[ ] Callouts match their purpose (note for context, warning for risks, etc.)
[ ] Callouts have titles (2-4 words, Title Case)
[ ] Maximum one callout per ~300 words of body text
[ ] Wikilinks point to existing articles
[ ] External links open in the same tab (KMS default)
[ ] Images have alt text and correct file paths
[ ] Code blocks specify their language

Final Check

[ ] Read the article aloud — does it flow?
[ ] Check the excerpt — does it accurately describe the article?
[ ] Preview in local development — do headings, tables, and callouts render correctly?

The Golden Rule

Write for the reader who has five minutes. Structure your article so they get the main point from the title and excerpt, the key arguments from the first paragraph, and the evidence from the sections that follow. Everything else is bonus.