Apprise Documentation Style Guide

This guide describes how we write documentation, not what tools we use.

It exists to keep documentation clear, consistent, and welcoming, while still allowing contributors to write in their own voice.

Core Principles

Clarity over cleverness

Prefer clear, direct language over wordplay or clever phrasing.

Practical over theoretical

Show how something works before explaining why.

Friendly but professional

Write as a helpful peer. Avoid marketing language or excessive formality.

Assume the reader is new

Do not assume prior knowledge of Apprise unless stated.

Tone and Voice

• Use a calm, confident tone
• Avoid sarcasm or humour that may not translate well
• Use second person (“you”) when appropriate
• Avoid imperative commands unless giving instructions

Structure and Formatting

Headings

• Use sentence case for headings
• Keep headings descriptive and short

Paragraphs

• Keep paragraphs short (3–4 lines max)
• Prefer bullet lists for multiple related items

Lists

• Use bullets for unordered lists
• Use numbered lists for sequential steps

Examples

Examples are strongly encouraged.

Good examples:

• CLI commands
• URL examples
• Configuration snippets
• Small, focused code blocks

Avoid:

• Overly large examples
• Abstract placeholders without explanation

Terminology

• Use consistent terminology across pages
• Prefer “notification service” over shorthand
• Avoid abbreviations unless commonly understood

Service Documentation

When documenting a service:

• Describe what the service does before how to configure it
• Include at least one working example
• Document limitations clearly
• Mention upstream requirements where relevant

Localization Considerations

• Avoid idioms and slang
• Keep sentences simple where possible
• Avoid culture-specific references

This helps translators and non-native readers.

What This Guide Is Not

• It is not a strict rulebook
• It does not enforce a single writing style
• It should not discourage contributions

If in doubt, prioritize clarity and helpfulness.