# Author Page

> Scaffold or draft new Zesu documentation to editorial standards. Use when creating a new page, writing a first draft, or helping a non-writer meet the documentation team's expectations.

- Skill: `consensys-incorporated/author-page-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add consensys-incorporated/author-page-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/consensys-incorporated/author-page-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: consensys-incorporated (https://skillmd.com/u/consensys-incorporated)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/consensys-incorporated/author-page-2

---


# 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):

```markdown
---
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):

```markdown
---
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):

```markdown
---
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):

```markdown
---
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`):

```markdown
## <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.