Author Page

Author a new documentation page

Help create a new documentation page that follows Zesu editorial standards from the start.

When to use

• You need to scaffold a new page or write a first draft.
• You are helping someone who is not a writer produce content that meets team expectations.

Inputs

Ask the user for any information they have not already provided:

1. Content type - what kind of page? (concept/explanation, how-to guide, onboarding/get-started, reference, or troubleshooting entry)
2. Topic - what is the page about?
3. File path - where should the file live? (Suggest one based on the content type if the user doesn't specify.)

Step 1: Determine conventions

Load the relevant rules:

• .cursor/rules/content-types.mdc - structural expectations for the content type.
• .cursor/rules/product-zesu.mdc - product-specific conventions.
• .cursor/rules/editorial-voice.mdc - tone and voice.
• .cursor/rules/markdown-formatting.mdc - formatting conventions.
• .cursor/rules/terminology.mdc - required terms and casing.

Check how existing pages in the same folder are structured. Match their conventions for headings, frontmatter fields, intro style, and parameter formats.

Step 2: Scaffold the page

Create the file with the correct structure for its content type.

Frontmatter

Follow Frontmatter in .cursor/rules/markdown-formatting.mdc (required description, recommended keywords, optional sidebar_label only when the default nav label would be too long or wordy, and the title vs duplicate H1 rule). Do not repeat or contradict that rule here.

Structure by content type

Concept / Explanation (for concepts/ folder):

---
description: <one sentence>
---

# <Topic name>

<Opening paragraph: what this is and why it matters. 2-3 sentences. Get to the point.>

## <First concept section>

<Explain the concept. No step-by-step instructions.>

## <Second concept section>

...

## Next steps

- [<Related how-to guide>](<relative link>)
- [<Related reference>](<relative link>)

How-to guide (for how-to/ folder):

---
description: <one sentence>
---

# <Action-oriented title: "Configure logging" not "Configuring logging">

<Opening paragraph: what the reader will accomplish. 1-2 sentences.>

## Prerequisites

- <Requirement 1>
- <Requirement 2>

## Steps

### 1. <First action>

<Instruction. One action per step.>

### 2. <Second action>

...

## Next steps

- [<Related content>](<link>)

Get-started / Onboarding (for get-started/ folder):

---
description: <one sentence>
---

# <Topic>

<Opening paragraph: what the reader needs to know. 1-2 sentences.>

## Prerequisites

- <Requirement>

## <Content sections>

<Structure based on topic: how-to steps for installation, short explanation for system
requirements, or reference-style facts for supported configurations.>

Reference (for reference/ folder):

---
description: <one sentence>
---

# <CLI option or method name>

<One sentence describing what the option or method does.>

## Syntax

<Show the command syntax or method signature.>

## Parameters

<Match the format used in surrounding reference pages in the same section.>

## Returns

<Describe the return value (omit for CLI option pages where it doesn't apply).>

## Example

<Working example.>

Troubleshooting entry (additions to docs/troubleshooting.md):

## <Short symptom or error message>

**Symptom:** <What the reader sees or experiences.>

**Cause:** <Why this happens, if known.>

**Fix:** <Steps to resolve it. Keep short; link to a how-to page for longer procedures.>

Step 3: Write the content

Fill in the scaffold with content based on what the user provides. Follow these rules:

• Voice: active, present tense, second person ("you"). Use contractions naturally.
• First sentence: get to the point. Answer "what" or "why" immediately.
• No em/en dashes: use commas, parentheses, or semicolons.
• Sentence case for all headings.
• One sentence per line, wrapped at roughly 80 columns.
• Code blocks: always include a language tag.
• Terminology: use the required forms from terminology.mdc.
• No marketing language: no "powerful," "seamless," "best-in-class."
• No invented product behavior: if you are not certain about a CLI option, parameter, configuration setting, or behavior, add a :::note admonition flagging it for review rather than stating it as fact.

Step 4: Verify the file is complete

Before finishing, check:

• Frontmatter has description; add sidebar_label only when the default nav label would be too long or wordy (see markdown-formatting.mdc).
• Opening paragraph answers "what" and "why" in the first 1-2 sentences.
• Structure matches the content type.
• Terminology matches terminology.mdc and product-zesu.mdc.
• Code blocks have language tags.
• No em dashes, en dashes, or marketing language.
• File name uses lowercase and dashes (configure-logging.md, not configureLogging.md).
• File is placed in the correct content-type folder.

Step 5: Remind the contributor

After creating the page, remind the user to:

1. Add the new page to sidebars.js in the correct category and position (sidebars are manually maintained, not autogenerated).
2. If any page was moved, renamed, or removed in the same change set, add redirects in vercel.json (see contributor-workflow.mdc).
3. Preview locally with npm start.
4. Check that the CI linter passes before requesting review.