# Authoring Standards

# KB Article Template

## Purpose

Use this template for every LinkUp knowledge base page. It keeps the public help simple while giving us a small implementation check under the same article.

## Page template

<table id="bkmrk-section-what-to-writ"><tbody><tr><th>Section</th><th>What to write</th></tr><tr><td>Title</td><td>Use a short task-based title, such as **Buy a ticket** or **Confirm an offline reservation**.</td></tr><tr><td>Public help</td><td>Explain the task in plain language for the reader. Use short steps and avoid developer wording.</td></tr><tr><td>Expected LinkUp behavior</td><td>State what the product should do when the feature works correctly.</td></tr><tr><td>Implementation status</td><td>Mark the feature as Implemented, Partial, Legacy Only, Missing, Planned, or Needs Verification.</td></tr><tr><td>Verification checklist</td><td>Add simple checks that prove the feature works in the web app, mobile app, admin panel, or scanner app.</td></tr><tr><td>Gaps / notes</td><td>Record anything unclear, risky, or different from the intended behavior.</td></tr></tbody></table>

## Writing rules

- Write for one audience at a time.
- Use second person: “you”.
- Keep each step to one action.
- Use **bold** for buttons, screens, and fields.
- Use `[VERIFY: ...]` when a screen, button, or workflow has not been confirmed.
- Do not describe planned features as live features.

## Implementation check table

<table id="bkmrk-expected-behavior-st"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Every KB page includes public help and internal implementation notes.</td><td>Implemented</td><td>BookStack</td><td>Create or review a page and confirm both sections exist.</td></tr><tr><td>Unconfirmed UI is marked before publishing.</td><td>Implemented</td><td>Authoring process</td><td>Search the article for `[VERIFY:` markers before release.</td></tr></tbody></table>

## Gaps / notes

This is the first local standard. Update it after the first five to ten articles if the structure feels too heavy or too light.

# Status Legend

## Purpose

Use this legend to label every LinkUp feature the same way. The label should describe the current truth, not the future plan.

## Status labels

<table id="bkmrk-status-meaning-when-"><tbody><tr><th>Status</th><th>Meaning</th><th>When to use it</th></tr><tr><td>Implemented</td><td>The feature exists and matches the intended workflow.</td><td>Use after the feature has been checked in the app, admin panel, API, or mobile app.</td></tr><tr><td>Partial</td><td>Some pieces exist, but the full workflow is not complete.</td><td>Use when web, mobile, admin, or backend support is uneven.</td></tr><tr><td>Legacy Only</td><td>The feature exists only in the old system or old screen.</td><td>Use when the feature has not moved into the current LinkUp surface.</td></tr><tr><td>Missing</td><td>The feature does not exist yet.</td><td>Use when no route, screen, admin tool, or mobile flow can be found.</td></tr><tr><td>Planned</td><td>The feature is intended but not live.</td><td>Use for roadmap items, proposed workflows, or future policy.</td></tr><tr><td>Needs Verification</td><td>The docs or code suggest the feature exists, but it has not been tested.</td><td>Use when a human needs to check the real screen before publishing.</td></tr></tbody></table>

## Rule of thumb

If we are not sure, use **Needs Verification**. Do not turn uncertainty into a confident help article.

## Implementation check table

<table id="bkmrk-expected-behavior-st"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Every KB article uses one of the approved status labels.</td><td>Implemented</td><td>BookStack</td><td>Review each page before publishing.</td></tr><tr><td>Unverified workflows stay marked until tested.</td><td>Implemented</td><td>Authoring process</td><td>Search BookStack for `Needs Verification` and `[VERIFY:`.</td></tr></tbody></table>

## Gaps / notes

This page is an authoring control. It does not prove whether a product feature works.

# Prompt Rules

## Purpose

Use these rules when asking Codex or Claude to draft a LinkUp KB article. The goal is simple public help plus clear implementation truth.

## Required prompt inputs

<table id="bkmrk-input-what-it-means-"><tbody><tr><th>Input</th><th>What it means</th><th>Example</th></tr><tr><td>Audience</td><td>Who the page is written for.</td><td>attendee, organizer, scanner, internal team</td></tr><tr><td>Topic</td><td>The task or question the page answers.</td><td>Buy a ticket</td></tr><tr><td>Doc type</td><td>The shape of the article.</td><td>how-to, troubleshooting, reference, policy</td></tr><tr><td>Feature area</td><td>The product area being documented.</td><td>payments, scanning, Discover, admin</td></tr><tr><td>Source context</td><td>The docs, code, screenshots, or notes the writer should rely on.</td><td>Route, screen, model, test plan, or audit note</td></tr></tbody></table>

## Prompt rule

Ask for one page at a time. Include source context before asking for the final article. If the source is uncertain, ask the model to mark it with `[VERIFY: ...]`.

## Banned habits

- Do not invent button names.
- Do not describe planned features as live.
- Do not use vague instructions like “click the button”.
- Do not bury implementation gaps in friendly wording.

## Implementation check table

<table id="bkmrk-expected-behavior-st"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>The prompt produces a public article and internal implementation notes.</td><td>Implemented</td><td>Authoring process</td><td>Generate one test page and confirm both sections exist.</td></tr><tr><td>The prompt supports BookStack-ready output.</td><td>Implemented</td><td>BookStack</td><td>Paste the article into BookStack and confirm headings/tables render cleanly.</td></tr></tbody></table>

## Gaps / notes

The reusable DOCX prompt should be updated after these first pages settle.

# BookStack book and chapter map

## Public help

Define where each type of LinkUp article belongs.

## Rule

Keep authoring simple, consistent, and honest about uncertainty.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Authoring standard is followed across pages.</td><td>Needs Verification</td><td>BookStack</td><td>Review a sample of pages after each batch.</td></tr><tr><td>Verification markers are resolved before public release.</td><td>Needs Verification</td><td>BookStack</td><td>Search for `[VERIFY:` before publishing.</td></tr></tbody></table>

## Verification checklist

- Review headings and structure.
- Check for unverified UI labels.
- Confirm status table exists.
- Confirm page is in the right book.

## Gaps / notes

- These standards should evolve after the first review pass.

# UI label verification checklist

## Public help

Prevent wrong button, screen, or field names from being published.

## Rule

Keep authoring simple, consistent, and honest about uncertainty.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Authoring standard is followed across pages.</td><td>Needs Verification</td><td>BookStack</td><td>Review a sample of pages after each batch.</td></tr><tr><td>Verification markers are resolved before public release.</td><td>Needs Verification</td><td>BookStack</td><td>Search for `[VERIFY:` before publishing.</td></tr></tbody></table>

## Verification checklist

- Review headings and structure.
- Check for unverified UI labels.
- Confirm status table exists.
- Confirm page is in the right book.

## Gaps / notes

- These standards should evolve after the first review pass.

# Article review checklist

## Public help

Review every page for clarity, status accuracy, and verification markers.

## Rule

Keep authoring simple, consistent, and honest about uncertainty.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Authoring standard is followed across pages.</td><td>Needs Verification</td><td>BookStack</td><td>Review a sample of pages after each batch.</td></tr><tr><td>Verification markers are resolved before public release.</td><td>Needs Verification</td><td>BookStack</td><td>Search for `[VERIFY:` before publishing.</td></tr></tbody></table>

## Verification checklist

- Review headings and structure.
- Check for unverified UI labels.
- Confirm status table exists.
- Confirm page is in the right book.

## Gaps / notes

- These standards should evolve after the first review pass.

# Screenshot placeholder rules

## Public help

Explain when to add screenshots and when to leave a verification placeholder.

## Rule

Keep authoring simple, consistent, and honest about uncertainty.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Authoring standard is followed across pages.</td><td>Needs Verification</td><td>BookStack</td><td>Review a sample of pages after each batch.</td></tr><tr><td>Verification markers are resolved before public release.</td><td>Needs Verification</td><td>BookStack</td><td>Search for `[VERIFY:` before publishing.</td></tr></tbody></table>

## Verification checklist

- Review headings and structure.
- Check for unverified UI labels.
- Confirm status table exists.
- Confirm page is in the right book.

## Gaps / notes

- These standards should evolve after the first review pass.