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

# Layout Rules For Help Icons

Adding help must not make the page layout worse. Help icons should be added inline beside existing labels or headings, using the same placement pattern as Characters/Details.

Do not wrap form controls in new layout containers unless necessary. Do not change Bootstrap grid structure unless the page already needs a layout fix. Preserve input widths and alignment.

For form fields, prefer placing the icon beside the label text. For checkboxes, place the icon beside the checkbox label text. Do not create floating controls.

Do not add extra margin, padding or background panels unless matching an existing pattern. After adding help, visually compare the page before and after so the page still looks deliberate and tidy.

# Field-Level Help Rules

Field-level help is for controls where the user may not understand what to choose. Do not add field help to obvious fields like name or description unless the field has special meaning.

Explain what the control means, what the user should choose and why it matters to writing continuity. Use concrete examples. Keep field help short and practical.

Section help should include an `# Understanding the Fields` section when a section has several non-obvious controls.

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