Doc Update Manual

Use this skill whenever a user-facing feature is added, changed, or removed: a new wizard, a renamed menu item, a new toolbar button, a changed workflow, or a new command-line option. The user manual must reflect what the application actually does; stale documentation is a defect.

Also use it proactively at the end of any task that changes UI behaviour, even if the user did not explicitly ask for a manual update.

1. Identify the affected chapter. The manual lives under doc/manual/user_guide/. The root file is user_manual.org; each chapter is a flat chapter_N_*.org file in the same directory. Map the changed feature to its chapter:

   Feature area	Chapter file
   Login, connections, status bar, CLI	chapter_2_connecting.org
   Bootstrapping, tenants, parties	chapter_3_initial_setup.org
   Reference data (currencies, etc.)	(future chapter)
   Instruments and trades	(future chapter)
   Market data	(future chapter)
   Analytics	(future chapter)

   If the feature does not map to an existing chapter, note it so a new chapter can be planned.

2. Update the prose. Edit the relevant .org file to reflect the new or changed behaviour. Keep the tone consistent: plain language, second person ("you"), British English, non-programmer audience. Describe what the user does and sees, not how the code works.

3. Add screenshot placeholders for any new UI. Every new dialog, page, or significant UI state needs a #+caption: block and a TODO_ placeholder link:

   #+caption: [SCREENSHOT NEEDED] <what to show>.
   # Capture: <precise instruction for what to capture and how>.
   [[proj:doc/assets/images/TODO_descriptive_name.png]]
   

   The link path is relative to the chapter file, which lives in doc/manual/user_guide/ — three levels above the repo-root assets/, hence ../../../.

   Name placeholder files with the TODO_ prefix so they stand out in the file list and are easy to search for.

4. Update existing screenshot captions if the UI changed enough that an existing screenshot is now wrong or misleading. Mark it:

   #+caption: [SCREENSHOT OUTDATED — retake needed] <updated description>.
   

5. Rebuild the PDF to verify the chapter compiles without errors:

   ./projects/ores.compass/compass.sh build --direct manual
   

   Fix any LaTeX errors before committing.

6. Commit the updated chapter on the relevant feature branch as part of the same PR as the code change. Documentation and code ship together; a PR that changes UI without updating the manual is incomplete.

7. Rebuild and commit the PDF if the content changed substantially enough to warrant an updated binary:

   ./projects/ores.compass/compass.sh build --direct manual
   git add doc/manual/user_guide/user_manual.pdf
   git commit -m "[doc] Rebuild user manual PDF"
   

• How do I address PR review comments? — the review loop that follows the PR containing manual updates.

• ORE Studio User Manual — the root manual file.
• doc/manual/user_guide/ — the root file plus the flat chapter_N_*.org source files.
• deploy_manual CMake target — builds the PDF via projects/ores.lisp/src/ores-build-manual.el.