Help Guide Writing Standard

Introduction

This document establishes the universal standards for creating effective help guide content across any SaaS or software platform. It defines expectations for page structure, content quality, visual consistency, terminology usage, and text formatting, ensuring that all help documentation maintains a professional standard and aligns with the product's brand positioning.

Understanding and implementing these guidelines will enable documentation teams to produce help content that supports platform adoption while maintaining consistency across the full documentation library.

Understanding Page Types

Why page type must be defined first

Before beginning any help guide page, you must identify and define its page type. The page type determines which structural guidelines apply throughout the content creation process. Different page types serve different user needs and require different approaches.

Page type categories

• Feature Explanation Page — describes a specific platform feature in comprehensive detail
• Additional page types should be defined by your documentation team as the library grows, each with clearly documented structural rules

Feature Explanation Page Structure

The Feature Explanation Page is a core documentation type. It must be constructed using the following components, in order.

1. Title

The title must follow this format:

[Feature Name] in [Platform Name] | [Component Name]

All titles use sentence case. Do not deviate from this format.

2. Introductory paragraph

The introductory paragraph must address four points:

• What the feature does
• When it is used
• Where it is found in the back-end interface
• Where it appears in the front-end experience

3. Front-end example with screenshot

Include a screenshot showing how the feature appears to end users. This establishes context before procedural content.

4. Prerequisites section

Title this section "Available in these plans:" and list the applicable subscription plans or access tiers.

5. Definition block

Title this block "Common terms people use to describe this feature:" and use it to acknowledge alternative terminology while reaffirming the official platform term.

6. Page section overview

Provide a numbered list of all major sections on the page. Each item should hyperlink to its corresponding section.

7. Content sections

Develop comprehensive sections covering all explanations and screenshots. Organize by the user's natural workflow.

8. "What's next?" section

Close every Feature Explanation Page with a bulleted list of related pages:

• Dashboard overview – Learn how to navigate the main dashboard and customize your view.
• Setting up notifications – Configure email and in-app alerts for your team.
• Managing team permissions – Control who can access and edit features.

Information Blocks

Tip blocks

Use for helpful but optional advice, best practices, and shortcuts.

Tip: You can press Ctrl+K to quickly search for any feature from anywhere in the platform.

Note blocks

Use for important facts, limitations, conditions, and system behavior.

Note: Custom fields are only available on Premium and Business plans. Free plan users will see a prompt to upgrade.

Definition blocks

Use to clarify the meaning of key concepts or indicate alternative terms.

Definition: Workspace — a collaborative environment where team members create and manage documentation. Some users may know this as a "project" or "channel."

Warning blocks

Reserve for serious situations only: data loss, errors, irreversible actions, billing implications, or security issues.

Warning: Deleting a workspace permanently removes all associated documentation, files, and revision history. This action cannot be undone.

Content Guidelines

Focus on non-obvious information

Direct content toward explaining things the UI does not make immediately obvious. Do not narrate what is self-evident from the screen. Use concise menu path summaries paired with screenshots.

Use realistic data and examples

All examples must be realistic and contextually relevant to actual usage. Never use Lorem Ipsum or nonsensical placeholder text.

Stay focused on platform capabilities

When a topic requires knowledge of a third-party tool, link to that tool's own documentation rather than documenting it here.

Visual Guidelines

Arrow style consistency

Use specific, defined arrow styles for specific purposes. Apply them consistently throughout all documentation.

Close-up screenshots

Each screenshot should focus on a single action or interface element. Do not illustrate multiple steps in a single visual.

AI Usage Guidelines

Permitted uses

• As a quick-start or rough draft tool to accelerate initial content production
• To generate a structural outline that is then verified and refined by a human writer
• To suggest phrasing, which must then be edited to conform to brand standards

Not permitted

• AI must never generate platform interface visuals or screenshots
• AI must never produce mockups of feature outcomes
• No AI-generated content may be published without thorough human review

Terminology Guidelines

Always use the platform's official terminology. Maintain a centrally managed glossary that defines all approved terms and flags common alternatives to avoid.

Tone of Voice

Concision

• Write one idea per paragraph, maximum four lines
• Break long explanations into subsections with descriptive sub-headers
• Use bullet points for options, examples, or lists
• Do not use nested bullet points

Encouraging language

• Use active verbs: "You can use..." not "The feature can be used..."
• Use confidence-building phrases: "You can easily..." and "You'll be able to..."
• Frame limitations as prerequisites rather than restrictions
• Insert micro-affirmations at transitions: "That's all you need to get started."

Text Formatting