How to Write Product How-To Docs for Your SaaS Tools

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).

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.

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.

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:

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

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.

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.