---
title: "How to Write Product How-To Docs for Your SaaS Tools"
sidebarTitle: "Writing Docs"
description: "Learn how to write focused, customer-ready how-to articles that guide users through tasks clearly and power accurate AI agent responses."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

A great how-to article solves exactly one problem. It opens by naming that problem plainly, walks the customer through a numbered sequence of steps, and ends by telling them what success looks like. When every article in your product collection follows this pattern, customers find answers quickly, support tickets decrease, and AI agents have clean, unambiguous content to draw from when generating responses. This page shows you how to build articles that clear all three bars.

## What Makes a Great Customer-Facing How-To Article

Before you open a new article, keep these four qualities in mind:

- **Single focused task.** Each article covers one thing. "How to export a report" is a good scope. "Reports overview and export and sharing and scheduling" is not — split that into four articles.
- **Clear, numbered steps.** Customers following instructions need to know exactly where they are in a process. Numbered steps make it impossible to lose your place.
- **Expected outcomes.** Tell customers what they will see when each major step succeeds. "A green confirmation banner appears" is far more reassuring than leaving them to wonder whether anything happened.
- **Screenshots where it matters.** A screenshot of a non-obvious UI element saves five minutes of confusion. You do not need one for every step — just for the ones where the interface is complex, cluttered, or frequently updated.

## Create a New Article

<Steps>
  <Step title="Select the product from your External KB dashboard">
    Navigate to **External KB → Products** and click the product you want to add content to. From the product's detail page you can see all existing articles organized by topic category, along with their current status (Draft, In Review, Published).
  </Step>

  <Step title="Click 'New Article' and choose a topic category">
    Click **New Article** in the top-right corner. A dialog asks you to select a topic category before you begin writing. Choose the category that best matches the task you are documenting. If no existing category fits, you can add a new one directly from this dialog without leaving the article creation flow.
  </Step>

  <Step title="Write a clear, action-oriented title">
    Your title should tell the customer exactly what they will accomplish by reading the article. Lead with a verb.

    **Strong titles:**
    - "How to reset your password"
    - "Connect your account to Slack"
    - "Export a contact list as a CSV file"
    - "Enable two-factor authentication"

    **Weak titles:**
    - "Password information" — no action, no clarity
    - "Slack" — too vague to be useful
    - "Data export options and related settings" — tries to cover too many things at once

    Customers scan article lists and search results. A verb-first title lets them confirm in under a second that they have found the right article.
  </Step>

  <Step title="Write the article body">
    Structure your body content in four parts:

    1. **Opening sentence** — One sentence that confirms the problem this article solves and who it is for. Example: *"If you need to share contact data with another system, you can export any filtered contact list as a CSV file directly from the Contacts dashboard."*
    2. **Prerequisites** — List anything the customer must have in place before starting (e.g., a specific role, a connected integration, a feature enabled by an admin). Keep this short — a bulleted list of two to five items is enough.
    3. **Numbered steps** — Walk through the task sequentially. Each step should describe one action and, where relevant, the outcome of that action. Include screenshots or annotated UI callouts for complex screens.
    4. **Expected result** — Describe what the customer sees when the task is complete. This gives them a concrete way to confirm they succeeded and a clear signal if something went wrong.

    For steps that involve code or configuration values, always use a fenced code block with the appropriate language tag:

    ```bash
    curl -X POST https://api.example.com/v1/export \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{"format": "csv", "filter": "all_contacts"}'
    ```
  </Step>

  <Step title="Add tags to improve search and AI discoverability">
    Tags help customers find your article through search and help AI agents retrieve the right content when answering questions. Add three to seven tags per article. Good tags include:

    - The product name (e.g., `salesforce`)
    - The task type (e.g., `export`, `reset`, `connect`)
    - Relevant feature names (e.g., `two-factor-authentication`, `csv`, `contacts`)
    - Common error messages or symptom keywords customers might search for

    Avoid tags that are too generic to be useful, such as `help` or `article`. These add noise without improving retrieval accuracy.
  </Step>

  <Step title="Set the article status">
    Choose a status before saving:

    - **Draft** — The article is a work in progress and is not visible to customers. Use this while you are still writing or waiting for a subject matter expert to review technical details.
    - **In Review** — The article is complete from a writing standpoint but needs sign-off before publishing. Assigning this status notifies the product owner and any designated reviewers.
    - **Published** — The article is live, visible to customers according to the product's visibility settings, indexed for search, and available to AI agents.

    Save the article at any status. You can promote it to Published whenever it is ready.
  </Step>
</Steps>

## Structuring a How-To Article

Every article you write should follow a consistent internal structure. This makes articles predictable for customers and easier for AI agents to parse.

| Section | Purpose | Length |
|---|---|---|
| Opening context | Name the problem and confirm who this article helps | 1–2 sentences |
| Prerequisites | List what must be true before the customer starts | 2–5 bullet points |
| Steps | Walk through the task in numbered sequence | As many as needed; aim for under 10 |
| Expected result | Describe what success looks like | 1–2 sentences |
| Related articles | Link to articles covering adjacent tasks or next steps | 2–4 links |

Keep each section lean. If your prerequisites section has eight items, consider whether this task should be broken into two articles — one that covers the setup and one that covers the main task.

## Good Example vs. Common Mistakes

<Tabs>
  <Tab title="Good Example">
    **Title:** How to connect Notion to your workspace

    **Opening context:**
    Connecting Notion to your workspace lets you sync pages and databases directly into your content pipeline without manual copy-pasting.

    **Prerequisites:**
    - You have a Notion account with admin permissions on the workspace you want to connect.
    - You have the **Integrations** feature enabled on your plan (Settings → Billing → Features).

    **Steps:**
    1. Go to **Settings → Integrations** and click **Add Integration**.
    2. Select **Notion** from the integration directory.
    3. Click **Connect** — a Notion authorization window opens in a new tab.
    4. Choose the Notion workspace you want to grant access to, then click **Allow Access**.
    5. Return to this tab. Your Notion workspace name appears in the integrations list with a green **Connected** badge.

    **Expected result:**
    Within two minutes, your connected Notion pages are available to select in **Content → Sources**. If the badge shows **Pending** for more than five minutes, disconnect and reconnect the integration.

    **Related articles:**
    - [Sync a Notion database to your KB](#)
    - [Manage integration permissions](#)
  </Tab>
  <Tab title="Common Mistakes">
    **Vague title:**
    ❌ "Notion stuff" — tells the customer nothing about what the article covers.

    **Missing opening context:**
    ❌ Jumping straight into steps with no explanation of what problem is being solved or who the article is for. Customers who land on your article from search need that one-sentence confirmation that they are in the right place.

    **Missing expected outcomes:**
    ❌ "Click Connect." — with no mention of what the customer should see next. When customers do not know what success looks like, they repeat steps unnecessarily or open a support ticket assuming something went wrong.

    **Walls of text:**
    ❌ Writing steps as a single paragraph: *"First go to Settings and then click Integrations and look for the Add Integration button which you will find in the top right corner and then..."* — customers cannot follow this at a glance. Use numbered steps, not run-on prose.

    **Internal jargon:**
    ❌ "Trigger the OAuth handshake via the ISP connector module." — customers do not know what any of that means. Write what they click, not what the system does internally.

    **Too many tasks in one article:**
    ❌ "Connecting, managing, and disconnecting integrations" all in one article with no clear sections. Split tasks into separate articles and link between them.
  </Tab>
</Tabs>

<Tip>
  Write at the level your customers actually operate at — not at the level of the engineers who built the product. If your customers are non-technical business users, avoid terms like "API endpoint", "OAuth token", or "payload" unless you define them immediately. When in doubt, ask: could a customer who is smart but has never seen this screen before follow these steps without asking anyone for help?
</Tip>

## Screenshot Guidelines

<Note>
  Screenshots are powerful when used correctly and a maintenance liability when overused. Follow these guidelines to get the most from them:

  - **Annotate complex screens.** Use arrows, numbered callouts, or highlighted boxes to point customers to the exact UI element they need to interact with. Do not make them hunt for a small button in a dense interface.
  - **Keep screenshots current.** An outdated screenshot of a UI that has since changed is worse than no screenshot at all — it actively misleads customers. When a product updates its interface, flag all articles in that product for screenshot review.
  - **Never include sensitive data.** Before uploading a screenshot, check for email addresses, API keys, customer names, account IDs, or any other data that should not be public. Use an image editor to blur or redact these values before uploading.
  - **Use consistent dimensions.** Crop screenshots to show only the relevant part of the UI. Full-screen screenshots at high resolution are often too large to read inline and force customers to open them separately.
</Note>