---
title: Help Authoring Guidelines
category: Internal
tags: help, authoring, guidelines
contextKey: internal.helpAuthoringGuidelines
micro: Internal guidance for writing PlotWeaver contextual help.
quickTitle: Help authoring guidelines
quickSummary: Internal guidance for applying the three-level help pattern across PlotWeaver Studio.
screenshot:
---

# Three-Level Help Pattern

Use this guideline when adding contextual help to a new PlotWeaver Studio area. The goal is to help authors understand the writing purpose of a page, section or field without exposing implementation details.

# Level 1: Page Help

Place page help beside the main H1. It should explain what the whole page is for, why an author would use it, how it fits the writing workflow and what the main sections mean.

Context key pattern: `area.page`, such as `characters.details`.

# Level 2: Section Help

Place section help beside H2 headings or major card headings. It should explain a specific feature, when to use it, how it affects story planning or continuity and what to avoid.

Context key pattern: `area.section`, such as `characters.initialRelationships`.

If a section contains several controls, include a `# Understanding the Fields` section with a simple table.

# Level 3: Field Help

Place field help beside labels or unclear controls. Keep it short, practical and specific. Field help should answer what the field means, what to choose, how it affects the story model and what mistake to avoid.

Context key pattern: `area.feature.field`, such as `characters.relationships.awareness`.

# When To Add Help

Add help when an author may ask what a field means, what choice to make, whether something is visible to readers, whether a value is story truth or character belief, or when a change becomes true in the story.

# When Not To Add Help

Do not add help to obvious fields such as name, short name, plain description fields or simple buttons. Do not add help just to decorate a page.

# Article Structure

Every article needs front matter with `title`, `category`, `tags`, `contextKey`, `micro`, `quickTitle`, `quickSummary` and `screenshot`. Leave `screenshot` blank unless a real screenshot file exists.

Use Help Centre links by context key, such as `/Help/Article/characters.details`. Do not link directly to `.md` files.

# Tone

Write for authors. Prefer concrete story examples over technical descriptions. Explain why a feature matters for scenes, continuity, reader knowledge, character belief, reveals or revision.

# Examples

Page key: `characters.details`

Section key: `characters.initialRelationships`

Field key: `characters.relationships.readerInitiallyKnows`