Split the user manual into Qt and Wt manuals

Table of Contents

This page is a capture in the inbox bucket of the product backlog — a pre-sprint idea, not yet pulled into a sprint as a story.

What

Today ORE Studio has a single user manual (under doc/manual/). As the Wt web front-end grows alongside the Qt desktop client, one manual covering both surfaces will become unwieldy. Split it into two: a Qt user manual and a Wt user manual. The Wt manual should be near-identical to the Qt one, diverging only where the apps genuinely differ (interaction model, navigation, deployment, screenshots). To avoid maintaining duplicate prose, consider driving the shared, identical sections through codegen — a single source rendered into both manuals — reserving hand-written content for the app-specific deltas. Codegen sharing is only feasible where the text is truly identical; anything that paraphrases per app stays hand-written.

Why

A single manual that interleaves Qt and Wt is harder to read and to keep correct: a reader of one surface has to wade through the other's specifics. Two focused manuals serve each audience directly. But naive duplication doubles the maintenance burden and invites drift between the near-identical sections — so the identical core should be generated from one source rather than copy-pasted. This also fits the existing model: the Doc technical space already generates manual chapters via codegen (see Applied MASD).

References

  • doc/manual/ — the current single user manual.
  • Wt facet / Qt facet — the two application surfaces.

See also

  • Applied MASD — the Doc technical space and codegen of doc artefacts.

Emacs 29.1 (Org mode 9.6.6)