Skip to main content

Help Content Management and Publishing Overview

This guide explains how Tailboom help content is created, maintained, indexed, built, and published across the docs source tree, the generated catalog, and the in-app help panel.

It is the starting point for anyone who needs to add a new help article, update an existing guide, or verify that the content pipeline still works end to end.

What this guide covers​

  • Where help content lives in the repository.
  • How an article is structured.
  • How the help key registry and generated catalog work.
  • How related guides are surfaced in the app.
  • How to publish and verify changes safely.

System overview​

The help system has one source of truth: markdown files under docs/help.

Those source files are transformed into two user-facing surfaces:

  • The docs site, which publishes the authored markdown as navigable documentation.
  • The in-app help panel, which renders the generated article index and related guides cards.
flowchart TD
  Author[Content author]
  Source[docs/help/**/*.md]
  Registry[docs/help/_meta/help-key-registry.yaml]
  Generator[scripts/docs/generate-help-catalog.mjs]
  Catalog[docs/help/catalog/*.json]
  HelpIndex[frontend/src/help/helpIndex.generated.ts]
  InApp[Operator App help panel]
  DocsSite[docs-dev docs site]
  Publish[GitHub Actions deploy]

  Author --> Source
  Source --> Registry
  Source --> Generator
  Registry --> Generator
  Generator --> Catalog
  Generator --> HelpIndex
  HelpIndex --> InApp
  Catalog --> DocsSite
  Publish --> DocsSite
  Publish --> InApp

Where content lives​

Source files​

Author help articles in docs/help, grouped by app and doc type.

  • docs/help/operator-app/product-guides/ for feature and process overviews.
  • docs/help/operator-app/how-to/ for task-focused instructions.
  • docs/help/operator-app/support-kb/ for troubleshooting and support notes.
  • Equivalent folders exist for admin-portal and pilot-life.

Templates and metadata​

  • docs/help/_templates/ contains the starter documents used for new articles.
  • docs/help/_meta/help-key-registry.yaml maps help keys to doc IDs.
  • docs/help/README.md documents the required fields and publishing workflow.

Generated outputs​

  • docs/help/catalog/ contains generated catalog and implementation evidence files.
  • frontend/src/help/helpIndex.generated.ts powers the in-app help lookup table.

Article format​

Every published article should include the required frontmatter fields:

  • id
  • title
  • app
  • doc_type
  • module_slug
  • roles
  • summary
  • owner
  • last_verified

Useful optional fields include:

  • tags for search and grouping.
  • source_paths for implementation evidence.
  • ui_quick_refs when the article maps to in-app navigation shortcuts or help keys.
  • related for cross-document relationships.

A good article body usually follows this shape:

  1. Short introduction.
  2. Main concept or workflow.
  3. Detailed steps or lifecycle explanation.
  4. Common mistakes or troubleshooting.
  5. Related guides.

Use a Related guides section in the source markdown when the article has obvious follow-on reading.

In the current in-app help experience, those related links are surfaced as cards below the article rather than as inline bullet points in the rendered body.

That means the source should be written for the docs pipeline first, while the app experience remains the polished navigation surface.

Content lifecycle​

flowchart TB
  Draft[Draft article in docs/help]
  Review[Check frontmatter, headings, and related guides]
  Register[Add or update help key registry entry]
  Generate[Run npm run docs:help:catalog]
  Validate[Review generated catalog and frontend help index]
  Build[Run frontend build and docs build]
  Publish[Deploy dev docs and app]
  Verify[Open article in docs site and in-app help panel]

  Draft --> Review --> Register --> Generate --> Validate --> Build --> Publish --> Verify

Creating a new article​

1. Choose the right lane​

Decide whether the article is a product guide, a how-to, or a support note.

For a broad process article about the help system itself, product-guide is usually the right fit.

2. Start from a template​

Copy the closest file in docs/help/_templates and rename it into the right app folder.

For Tailboom help process content, use the operator-app product guides lane.

3. Fill in frontmatter carefully​

Keep the id stable once published. If the title changes later, update the title but try not to rename the id unless you are intentionally moving the article.

Example fields that matter most:

---
id: operator-help-content-management-and-publishing-overview
title: Help Content Management and Publishing Overview
app: operator-app
doc_type: product-guide
module_slug: core.help.content-management
summary: How Tailboom help content is authored, indexed, built, published, and maintained.
owner: core-help
last_verified: 2026-06-21
---

4. Write the body in clear sections​

Use short, stable headings so the in-app section chips stay useful.

Recommended headings for process content:

  • What this guide covers
  • System overview
  • Where content lives
  • Article format
  • Content lifecycle
  • Creating a new article
  • Updating an existing article
  • Publishing and verification
  • Troubleshooting

If the article should surface follow-on reading, add a Related guides section in the source markdown.

Prefer related titles that already exist in the same app so the in-app cards resolve reliably.

6. Register the help key​

Add a matching entry to docs/help/_meta/help-key-registry.yaml.

This is what connects the article to the generated help key index used by the app.

7. Generate the catalog​

Run:

npm run docs:help:catalog

This regenerates the catalog JSON outputs and frontend/src/help/helpIndex.generated.ts.

8. Build and verify​

Run the frontend build and inspect the generated article in both surfaces:

  • The docs site should render the article markdown.
  • The in-app help panel should render the generated content and related cards.

Updating an existing article​

When maintaining content, prefer the following order:

  1. Update the markdown source file.
  2. Keep the id stable unless the article is being retired.
  3. Refresh last_verified when the content has been checked against the current product.
  4. Update related guides if the cross-links changed.
  5. Regenerate the catalog and rebuild the app.

If the article depends on code paths, make sure source_paths still point to real files.

If the article depends on a UI flow, verify the flow in the app before you mark it current.

Publishing and verification​

The practical publish loop is:

  1. Edit the source markdown.
  2. Update the registry entry if the article is new.
  3. Run the help catalog generator.
  4. Commit and push.
  5. Let the docs and app deployment workflows run.
  6. Verify the article in docs-dev and in the in-app help panel.

The most important checks are:

  • The article appears in the catalog.
  • The help key resolves in the app.
  • Related guides show as cards.
  • Internal links and source paths are valid.
  • Headings still produce useful section navigation.

Common mistakes​

  • Editing generated files directly instead of the source markdown.
  • Forgetting to add the registry entry for a new article.
  • Using a heading that does not match the article title or topic.
  • Linking to a document that does not exist in the same app.
  • Letting last_verified drift away from the real verification date.

Troubleshooting​

The article does not appear in the app​

Check that the registry entry exists, the doc ID matches, and the generator has been run.

Check the Related guides section in the source markdown and confirm the titles match real documents in the same app.

The article appears in docs but not in the help panel​

Check the generated frontend/src/help/helpIndex.generated.ts file and confirm the help key was regenerated.

A source path is reported as missing​

Confirm the path exists in the repository and is not stale after a refactor.

Maintenance checklist​

Before closing a docs change, confirm the following:

  • The frontmatter is complete.
  • The article title and summary are accurate.
  • The registry entry exists if the article is new.
  • The Related guides section points to real content.
  • npm run docs:help:catalog completes successfully.
  • The frontend build still passes.
  • The published article reads cleanly in the app.
  • Help Catalog
  • Forms and Signing Overview