3.8 KiB
title, category, tags, contextKey, micro, quickTitle, quickSummary, screenshot
| title | category | tags | contextKey | micro | quickTitle | quickSummary | screenshot |
|---|---|---|---|---|---|---|---|
| Help Authoring Guidelines | Internal | help, authoring, guidelines | internal.helpAuthoringGuidelines | Internal guidance for writing PlotDirector contextual help. | Help authoring guidelines | Internal guidance for applying the three-level help pattern across PlotDirector. |
Three-Level Help Pattern
Use this guideline when adding contextual help to a new PlotDirector 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