Documentation style guide

These guidelines help keep Ablebase documentation consistent, clear, and useful. Follow them when writing or updating any page on this site.

Principles

Concise but friendly

Most readers are here to complete a task, so respect their time. Cut unnecessary words, but don’t sound robotic — a conversational tone is fine as long as it doesn’t get in the way of instructions.

Task-oriented

Lead with what the reader needs to do. Explain concepts only when they’re required to complete a task or make a decision.

Accessible to all skill levels

Don’t assume deep technical knowledge. When you must use a technical term, link to a definition or explain it briefly on first use.

Audience

Ablebase documentation is written for administrators and end users who need to set up, configure, and use the platform. Some readers may be technical; many won’t be. Write for the least experienced reader without patronizing the most experienced one.

Voice and tone

• Write as you’d speak to a colleague, then tidy it up.
• Be direct. Use imperative mood for instructions.
  • Do: “Open the Settings page.”
  • Don’t: “The Settings page can be opened.”
• Use contractions (“don’t”, “you’ll”, “it’s”).
• Avoid idioms — they translate poorly and can confuse non-native speakers.
  • Do: “As a general rule”
  • Don’t: “As a rule of thumb”
• Don’t use “easy”, “simply”, “just”, or “obvious”. If something were obvious, the reader wouldn’t need documentation.
• Avoid double negatives.
• Don’t use sarcasm or irony.
• Avoid the possessive “our” when referring to the product.
  • Do: “In the Ablebase dashboard…”
  • Don’t: “In our dashboard…”

Grammar and usage

• Oxford English spelling. “Colour”, not “color”. Use “-ise” over “-ize” (e.g., “organise”, “customise”).
• Sentence case for headings. “Environment variables”, not “Environment Variables”.
• Capitalize only proper nouns and product names. “Open a project”, not “Open a Project”.
• Use contractions. “Don’t” over “Do not”.
• Avoid positional language.
  • Do: “The following list”
  • Don’t: “The list below”
• Use active voice. Put the subject first.
  • Do: “Ablebase creates a config file.”
  • Don’t: “A config file is created by Ablebase.”

Formatting

Headings

• Use ## for top-level sections within a page. Reserve # for the page title (set via frontmatter).
• Don’t skip heading levels (e.g., don’t jump from ## to ####).

Lists

• Use bulleted lists for unordered items.
• Use numbered lists only when sequence matters (e.g., steps in a procedure).
• Start each item with a capital letter. Use a period only if the item is a full sentence.

Code

• Use inline code (backticks) for file names, commands, config keys, and values.
• Use fenced code blocks with a language identifier for multi-line examples.
• Keep code examples minimal and realistic — show what someone would actually use in practice.

Links

• Use descriptive link text. Avoid “click here” or bare URLs.
  • Do: “See the environment variables reference.”
  • Don’t: “Click here.”
• When referencing another page in these docs, link to it rather than duplicating its content.

Images

• Include alt text on every image.
• Show only the relevant portion of the UI, not the entire screen.
• Use realistic, meaningful content in screenshots (e.g., actual field labels, not “Lorem ipsum”).

Page structure

Every page must include title and description in its frontmatter:

---
title: Configuration
description: How to configure Ablebase after installation.
---

A typical page follows this structure:

1. Opening sentence — one or two lines explaining what this page covers and why the reader needs it.
2. Sections — logically ordered ## headings, each covering one topic.
3. Next steps (optional) — link to related pages at the end.

Publishing checklist

Before merging a documentation change:

• Spell-check the text (use an automated tool).
• Have someone else proofread it.
• Test all links.
• Verify images have alt text.
• Confirm there’s no private or sensitive information.
• Ensure the page has title and description frontmatter.