In-App Docs Authoring

Use this workflow for BetterFleet in-app help documentation. The product repo is the source of truth, with bf-manage-web as the first concrete example.

Use GitLab Feature Flags with this guide for Manage feature-flagged behavior so doc timing and visibility match the rollout stage.

Quick workflow

Use one of these two workflows:

• Codex-driven workflow: the primary workflow for most documentation changes
• Hand-editing workflow: for small surgical edits where you do not need Codex to help with screenshots, structure, or navigation

Codex-driven workflow

Use this by default.

1. Work out what changed for the user.
2. If the change affects what users see, expect, notice, or need to do, the docs likely need updating.
3. Ask Codex to update the docs and tell it to use help-docs-authoring skill.
4. Include what changed, which area of the product it affects, and whether screenshots are needed.
5. Let Codex find and update the right page.
6. For Manage, this will normally be under bf-manage-web/docs/help/.
7. Codex should update the existing page first and only change structure when needed.
8. If screenshots are needed, give them to Codex for review.
9. Either paste the screenshot into Codex or save it to scratch/docs-images/.
10. Codex should check that the screenshot is suitable, place accepted images into committed docs assets, and insert the markdown reference.
11. If a screenshot is still missing, let Codex leave the standard TODO(doc-image) placeholder and tell you what still needs to be captured.
12. Review the resulting change as normal.
13. Confirm the wording matches the shipped behavior and that any navigation changes are intentional.
14. Create a merge request in the product repo.
15. For Manage docs, the change belongs in bf-manage-web and should go through the normal merge request and review process for that project.

Hand-editing workflow

Use this only for small surgical edits.

1. Work out what changed for the user.
2. If the change affects what users see, expect, notice, or need to do, the docs likely need updating.
3. Find the existing page first.
4. For Manage, start in bf-manage-web/docs/help/ and update the page that already matches the feature or workflow before creating anything new.
5. Edit the markdown directly.
6. Update the relevant index.md page so the guidance matches the shipped behavior.
7. Keep it task-oriented and concise.
8. Update navigation only if the structure changed.
9. Edit bf-manage-web/docs/help/nav.json only when a page is added, removed, renamed, or moved.
10. If screenshots are needed, switch back to the Codex-driven workflow.
11. That is the safer path for reviewing, naming, placing, and linking images.
12. Create a merge request in the product repo.
13. For Manage docs, the change belongs in bf-manage-web and should go through the normal merge request and review process for that project.

What belongs in in-app docs

• task-oriented help that users need while using the product
• explanations of user-visible behavior
• explanations of user-relevant system behavior that changes what users should expect, notice, or do

Do not use this workflow for BF Dev specs, BF Dev challenges, or support microsite content. Those are separate editorial streams.

Source of truth

• Keep in-app help docs in the product repo.
• Manage source of truth:
  • markdown pages: bf-manage-web/docs/help/**/*.md
  • navigation: bf-manage-web/docs/help/nav.json
  • committed images: bf-manage-web/docs/help/_assets/
• For Manage, documentation changes should be proposed and reviewed through a normal merge request in the bf-manage-web project.
• Keep front matter minimal and local-only. Preserve only metadata needed by the product repo. Do not add external source metadata.

When docs must be updated

Update in-app docs whenever a change affects what users see, expect, notice, or need to do.

This includes:

• user-visible behavior changes
• labels, helper text, and page wording changes
• onboarding and task-flow changes
• docs navigation or structure changes
• behind-the-scenes behavior changes that alter user expectations or required user action

If a code change ships without a corresponding docs update when one is needed, that is incomplete work.

When rollout uses a Manage feature flag:

• do not update general help as if the feature is broadly available while it is still Internal or Pre-Release
• update help for the intended current audience when the flagged behavior changes what those users should see, expect, or do

Editing pages and navigation

For Manage, edit the relevant page under bf-manage-web/docs/help/ before creating new pages.

• Prefer updating the existing page that matches the feature or workflow.
• Add or move pages only when the information architecture genuinely needs to change.
• Update nav.json only when a page is added, removed, renamed, or moved.
• Prefer relative markdown links between docs pages.
• Prefer committed asset references under _assets/.

Screenshot workflow

Place candidate screenshots in the shared intake folder:

• scratch/docs-images/

If it is easier, paste a screenshot straight into Codex first so it can be reviewed.

• If Codex already has a local file path for the image, it can copy it into the docs asset workflow directly.
• Otherwise, save the same image into scratch/docs-images/ before asking Codex to promote it into committed docs assets.

Before committing any screenshot to docs, review it to confirm that it:

• matches the page and state described in the documentation
• is readable
• is cropped appropriately
• does not expose secrets, personal data, or environment-only noise
• reflects the intended product, environment, and version closely enough for the documentation need

If a screenshot is not suitable, recapture it before ingesting it.

Accepted screenshots are copied into the committed product docs assets directory. For Manage, that is bf-manage-web/docs/help/_assets/.

Use descriptive slugged filenames:

• <doc-slug>-<short-topic>.<ext>

Promoting screenshots into committed assets

Use Codex to copy a screenshot from scratch/docs-images/ into the committed docs assets directory, rename it consistently, and print the markdown snippet to insert.

Manage example:

python3 .agents/skills/help-docs-authoring/scripts/ingest_doc_image.py \
  --source scratch/docs-images/sign-in-page.png \
  --docs-root bf-manage-web/docs/help \
  --doc-path getting-started/index.md \
  --topic sign-in-page \
  --alt "Sign in page"

Do not link to files directly from scratch/.

Missing screenshots

If a screenshot is relevant but not yet available, insert an HTML comment placeholder instead of visible text:

<!-- TODO(doc-image): capture <what to show>; save to scratch/docs-images/; ask Codex to ingest -->

When asking someone to capture a screenshot, specify the exact screen state that should be shown.

Using Codex

When working with Codex on in-app help documentation, ask it to use the help-docs-authoring skill.

Manage is the first implementation. Plan can adopt the same workflow later without changing the overall process shape.