Writing Documentation

This guide covers how to write excellent documentation for WISEROWS using our rich component system.

File Structure

Documentation files live in docs/content/ as Markdown files with YAML frontmatter:

---
title: Page Title
slug: url-slug
description: One-line description for SEO and previews.
category: getting-started
categoryLabel: Getting Started
sortOrder: 0
icon: rocket
---

# Page Title

Your content here...

Frontmatter Fields

7 of 7

Field	Required	Description
`title`	Yes	Page title shown in sidebar and header
`slug`	Yes	URL path segment (e.g., `quick-start` → `/docs/quick-start`)
`description`	Yes	Meta description for SEO and page subtitle
`category`	Yes	Category key for grouping (kebab-case)
`categoryLabel`	Yes	Display label for the category
`sortOrder`	Yes	Order within category (0-based)
`icon`	No	Lucide icon name for sidebar and header

Writing Principles

Lead with the outcome

Start every page with what the reader will achieve. Don't start with background — start with value.

Good: "Get your first project set up and start working with data in under 5 minutes." Bad: "WISEROWS was designed with flexibility in mind. In this section we will explore..."

Use headings as a scannable outline

Readers scan headings before reading content. Each ## heading should make sense as a standalone item in a table of contents. Use ### for sub-sections, #### sparingly.

One idea per paragraph

Short paragraphs. One concept each. Use bullet lists for multiple related items.

Show, don't just tell

Use code examples, screenshots, and interactive components. A working example is worth more than paragraphs of explanation.

Use callouts for important information

Reserve callouts for genuinely important information — tips, warnings, and gotchas that readers should not miss.

Available Components

Cards

Use cards to link to related pages or highlight features. Wrap in <card-group> with a cols attribute.

<card-group cols="2">
<card title="Quick Start" icon="zap" href="/docs/quick-start">
Get up and running in 5 minutes.
</card>
<card title="API Reference" icon="key" href="/docs/api-authentication">
Integrate with the REST API.
</card>
</card-group>

Quick Start

Get up and running in 5 minutes.

API Reference

Integrate with the REST API.

Steps

Use steps for sequential instructions. Wrap content in <steps> with <step title="..."> elements.

<steps>
<step title="First step">
Do the first thing.
</step>
<step title="Second step">
Then do the second thing.
</step>
</steps>

First step

Do the first thing.

Second step

Then do the second thing.

Callout Boxes

Six types of callout boxes for drawing attention:

<note>Informational content.</note>
<tip>Helpful suggestion.</tip>
<warning>Proceed with caution.</warning>
<danger>Critical — may cause data loss.</danger>
<info>Additional context.</info>
<check>Verification or success message.</check>

Note

This is a note — use for informational content that adds context.

Tip

This is a tip — use for helpful suggestions and best practices.

Warning

This is a warning — use when the reader should proceed with caution.

Danger

This is a danger callout — use for critical warnings that may cause data loss.

Check

This is a check callout — use for verification or success messages.

You can also use GitHub-style callouts in standard markdown:

<tip>

This is a tip using GitHub syntax.

</tip>

Accordion

Use accordions to hide detailed content that most readers can skip:

<accordion title="Click to expand">
Detailed content that is hidden by default.
</accordion>

API Parameter Fields

Document API parameters with structured formatting:

<param-field name="entityTypeId" type="string" required="true">
The entity type to query.
</param-field>

<param-field name="limit" type="number" defaultValue="50">
Maximum number of results (max: 200).
</param-field>

entityTypeIdstringrequired

The entity type to query.

limitnumber

Maximum number of results (max: 200).

Response Fields

Document API response shapes:

<response-field name="data" type="Entity[]">
Array of entity objects.
</response-field>

dataEntity[]

Array of entity objects matching the query.

Tables

Markdown tables automatically render as interactive, sortable, searchable tables (for tables with 3+ rows).

| Name | Type | Description |
|------|------|-------------|
| title | text | Page title |
| slug | text | URL segment |
| status | select | Draft or published |

Frame

Wrap images or screenshots with a styled border and optional caption:

<frame caption="The entity table view">

![screenshot](/img/table-view.png)

</frame>

Content Structure Best Practices

Start with Why

Open with the problem this page solves. Why should the reader care?

Use Visual Hierarchy

h2 → h3 → h4. Never skip levels. Use bold for inline emphasis.

Code Examples First

When documenting APIs or features, lead with a code example, then explain.

Link Generously

Cross-reference related pages. Internal links help readers discover features.

Page Template

Here's a recommended structure for most documentation pages:

# Feature Name

One-paragraph overview of what this feature does and why it matters.

## Quick Example

Code example or screenshot showing the feature in action.

## How It Works

Detailed explanation broken into logical sections.

### Sub-Feature A

Details...

### Sub-Feature B

Details...

## Configuration

Settings and options.

## Common Patterns

Real-world usage examples.

## Troubleshooting

Common issues and solutions (if applicable).

## Related

Links to related documentation pages.

Writing Documentation

Writing Documentation

Lead with the outcome

Use headings as a scannable outline

One idea per paragraph

Show, don't just tell

Use callouts for important information

Quick Start

API Reference

First step

Second step

Start with Why

Use Visual Hierarchy

Code Examples First

Link Generously

Command Palette