Formatting guidelines

Consistent formatting is essential for producing clear, readable, and professional technical documentation. Good formatting enhances usability, supports accessibility, and ensures that content remains maintainable and scalable as products evolve.

These guidelines provide a framework for structuring content, choosing typography, managing visual hierarchy, and applying brand standards across all technical writing.

Purpose

The goal of formatting guidelines is to create documentation that is:

• Readable: easy to scan and understand
• Visually consistent: across pages, writers, teams, and versions
• Accessible: usable by people of all abilities
• Brand-aligned: matching your organization's visual identity

Whether your content is published in a knowledge base, integrated within a product, or exported to PDFs, your formatting should be predictable, consistent, and aligned with your brand guidelines.

Typography

Choose fonts that are clear, readable, and aligned with your organization's brand guidelines.

Font types

• Body text: Use a legible, web-safe font that supports long-form reading. Examples: Inter, Roboto, Georgia, Open Sans, Helvetica (or your brand-approved equivalent).
• Headings: Use a font that creates a clear visual hierarchy and pairs well with the body text. Examples: Lato, Montserrat, Titillium Web, or any brand-approved display or geometric font.
• Code: Use a monospace font for code samples to distinguish them visually. Examples: Consolas, Courier New, Fira Code.

Font sizes

• Headings: Follow a clear hierarchical structure (for example, H1 → H2 → H3 → H4). Each level should be visually distinct to guide readers through the content.
• Body text: Choose a size that is comfortable for extended reading, typically 14–16 px for digital content (or an equivalent point size in print materials).
• Code blocks: Use a monospace font sized slightly smaller than body text, generally 85%–95% of the body text size.

General text rules

• Use single spacing for paragraphs.
• Left-align all text for optimal readability.
• Avoid justified text (creates uneven spacing).
• Avoid bold + italic combinations except for specific semantic meaning.

Colors and Highlighting

Brand and color usage

Follow your brand's approved color palette. If no palette exists, apply these universal rules:

• Use color only to enhance clarity, not decoration.
• Apply highlight colors consistently (e.g., for callouts or UI states).
• Do not rely on color alone to convey meaning — pair color with an icon, label, or text so the meaning still comes through for readers who can't perceive the color difference.

Contrast

Maintain WCAG-compliant contrast ratios:

• Normal text: 4.5:1
• Large text: 3:1

Avoid these color practices:

• Red text for normal emphasis
• Low-contrast "light gray on white"
• Neon or overly saturated colors that strain readability
• Large areas of colored, highlighted text

Highlighting

• Use bold for UI labels or emphasis.
• Avoid excessive underlining or italics (reduces readability).
• Avoid color highlighting unless required by your design system.

Headings and Hierarchy

Use a clear and logical heading structure:

• H1 — Page or article title (should appear once)
• H2 — Major sections
• H3 — Subsections
• H4 — Nested details (only when necessary)

Guidelines:

• Do not skip heading levels.
• Use sentence case for all headings. (See the Capitalization guide for the full sentence-case rule and examples — this article follows the same convention.)
• Prefer clear, descriptive titles over question-format headings as the default: "Managing categories," not "How do I manage categories?"

Exception: question-format headings are appropriate specifically in FAQ articles, or in individual sections written to directly answer a common search query, since question phrasing can improve visibility in search results and AI-generated answers (AEO). Outside of that specific, deliberate case, default to descriptive titles — don't mix the two styles within the same article for inconsistent reasons.

Callouts and Notes

This knowledge base uses four callout types — Note, Tip, Important, and Warning — each with a distinct purpose and severity level. For the full definitions, placement rules, language guidance, and accessibility requirements, see the dedicated Callouts guide, which is the authoritative source for callout usage.

As a quick summary:

Keep callout content short — one to two sentences, per the Callouts guide. If a callout needs a full paragraph or a list, the content likely belongs in the body of the article instead, with the callout reserved for a brief pointer to it. Callout type must never be conveyed by color alone — always pair color with a text label, per the accessibility rule in the Colors and Highlighting section above.

Tables

Use a table when readers need to compare structured values across more than one dimension — not simply to display a list of items with a single attribute each (use a bulleted list for that instead).

• Always include a header row, and mark it as a header (not just bold text) so screen readers announce it correctly.
• Keep cell content brief; if a cell requires more than a sentence or two, the content probably belongs in prose above or below the table instead.
• Avoid merged or nested cells where possible — they are difficult for screen readers to interpret and often render inconsistently across export formats (PDF, print).

Links

• Write link text that describes the destination on its own, without relying on surrounding sentence context: "see the release notes for details," not "click here for details."
• Never use a bare URL as visible link text in prose; always wrap it in a descriptive phrase.
• Distinguish links visually from surrounding text (underline and/or color) consistently across the knowledge base, and ensure link color meets the same contrast requirements as body text.

Code Blocks

• Use fenced code blocks with a language tag (for example, ```json) so syntax highlighting renders correctly and the content is identifiable to screen readers and automated tools alike.
• Keep code samples within a reasonable line length so they don't require horizontal scrolling on common screen sizes; break long lines using the target language's own conventions rather than inserting arbitrary line breaks.
• Use inline code formatting for short values referenced in prose (parameter names, file paths, single commands), and reserve fenced code blocks for multi-line samples.

Media Guidelines

Ensure all media is purposeful and enhances the content by providing clear visual support for the instructions. For detailed guidance on when to use images, screenshot annotation conventions, alt text, and the full media file naming convention, see the dedicated Images, Screenshots, and Video guide, which is the authoritative source for these topics.

General media best practices

• Use high-quality PNG or JPEG images for screenshots.
• Use optimized GIFs (under 10 MB) to demonstrate short workflows and animations.
• For longer workflows, prefer a short video over a GIF; provide captions or a text transcript alongside any video for accessibility.
• Insert UI icons inline with feature names where applicable (for example, Settings ⚙).
• Use predefined variables for feature names and repeated UI terms to ensure consistency.
• Blur any sensitive or personal data in screenshots.
• Ensure all media reflects the current product UI, and flag screenshots for review whenever the underlying UI changes.

File naming

Media file names follow a numbered type prefix plus a hyphenated, lowercase description — see the Media File Names section of the Images, Screenshots, and Video guide for the full convention and examples.

Dark Mode and Theme Variants

If your knowledge base or product supports a dark-mode or alternate theme, verify that contrast ratios, callout colors, and screenshot legibility hold up in every supported theme — not just the default. Screenshots taken in one theme should either be retaken for the other, or clearly labeled if a theme-specific difference is being illustrated deliberately.

Page Layout Standards

• Maintain consistent margins across exported documents (such as 1-inch margins on all sides).
• Avoid overusing horizontal lines. Use them only after major (H2) sections.

Examples and Templates

• Provide visual examples of well-formatted articles, including headings, lists, tables, and callouts.
• Offer reusable templates for common article types, such as:
  • FAQs
  • Troubleshooting guides
  • Release notes
  • Use-case-based articles

Self-Audit Checklist

Before publishing, check formatting against these questions:

• Do headings follow a strict hierarchy (H1 → H2 → H3 → H4) with no skipped levels?
• Are all headings in sentence case, and descriptive rather than question-format (unless this is a deliberate FAQ/AEO exception)?
• Does every callout use one of the four defined types (Note, Tip, Important, Warning) with no ad hoc labels?
• Do all color choices meet WCAG contrast ratios, and does color never carry meaning alone?
• Are tables used only for genuinely structured, multi-dimensional data, with a marked header row?
• Is link text descriptive out of context, with no bare URLs or "click here"?
• Do code blocks use a language tag and reasonable line lengths?
• Does every image and video have descriptive alt text or a caption/transcript?
• Are media file names following the numbered-type-prefix, hyphenated naming convention?
• Does formatting (contrast, callouts, screenshots) hold up correctly in dark mode or other supported themes?
• Are screenshots current with the live product UI?