Writing Documentation

This guide covers best practices for creating clear, useful support documentation using Scitor’s knowledge base feature.

File organization

Organize your docs folder by topic, with each folder representing a section:

docs/
├── index.md                 # Homepage with overview and quick links
├── getting-started/
│   ├── index.md             # Section intro
│   ├── installation.md      # Step-by-step install guide
│   └── quickstart.md        # Quick start tutorial
├── features/
│   ├── index.md             # Feature overview
│   ├── feature-a.md
│   └── feature-b.md
├── api/
│   ├── index.md             # API overview
│   ├── authentication.md
│   └── endpoints.md
└── troubleshooting.md       # Common issues and solutions

Frontmatter essentials

Every page should have a title and description at minimum:

---
title: Authentication
description: How to authenticate API requests with tokens and API keys.
order: 1
---

The order field controls sidebar position. Use increments of 10 (10, 20, 30) so you can insert pages later without renumbering.

Featured and related articles

Highlighting important content

Mark your most important articles with featured: true to promote them on the cards homepage:

---
title: Getting Started
description: Set up your account in under 5 minutes.
featured: true
---

Choose up to 5 articles to feature. Good candidates are:

• Getting started guides
• Most-visited troubleshooting pages
• Key workflow documentation
• Recently updated content about new features

Cross-linking with related articles

Add related slugs to connect articles together. Related articles appear as a card grid at the bottom of the page:

---
title: Email Setup
related: [getting-started, custom-email-domain, commands]
---

The slug matches the URL path of the target article. For nested pages, use the full path:

related: [getting-started/email-setup, guides/custom-email-domain]

Tips for related articles:

• Link to 2-4 related articles per page (enough to be helpful, not overwhelming)
• Create bidirectional links when it makes sense (if A links to B, consider linking B to A)
• Unknown slugs and hidden pages are silently skipped, so links won’t break if you reorganize

Writing style tips

Lead with the outcome

Start each page by explaining what the reader will learn or accomplish:

# Setting up webhooks

Learn how to configure webhooks to receive real-time notifications
when events occur in your account.

Use headings for scanning

Readers scan documentation, they don’t read it linearly. Use clear, descriptive headings:

## Prerequisites        ✅ Clear
## Before you begin     ✅ Clear
## Step 1: Install      ✅ Clear
## Configuration        ❌ Too vague
## The thing            ❌ Unclear

Use callouts strategically

Callouts draw attention — use them sparingly for maximum impact:

Show, don’t tell

Include code examples whenever possible:

# Good: concrete example
curl -X POST https://api.example.com/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"url": "https://yourapp.com/webhook"}'

Use tables for comparisons

Tables are great for feature comparisons, API parameters, and option lists:

| Parameter | Type   | Required | Description           |
|-----------|--------|----------|-----------------------|
| `url`     | string | Yes      | The webhook endpoint  |
| `events`  | array  | No       | Events to subscribe   |
| `secret`  | string | No       | Signing secret        |

Search optimization

Scitor’s search indexes page titles, descriptions, content, and tags. To make your pages easy to find:

1. Use descriptive titles — “Setting up email forwarding” not “Email”
2. Write meta descriptions — Include key terms the reader might search for
3. Add tags — Tag pages with alternative terms:

---
title: Rate Limiting
tags: [throttling, limits, 429, too-many-requests]
---

Images and assets

Place images in a subfolder within your docs directory:

docs/
├── images/
│   ├── screenshot.png
│   └── diagram.svg
└── getting-started.md

Reference them with relative paths:

![Dashboard screenshot](images/screenshot.png)

Images are automatically uploaded to the CDN during the build process.

Keeping docs up to date

• Review docs when shipping features — Make doc updates part of your PR process
• Link to docs from release notes — Help users find the right documentation
• Use hidden: true for work-in-progress pages that aren’t ready for publication
• Use Git blame to see when a page was last updated