docs: improve end-user documentation (format, structure, and consolidation across BESSER + WME)

[ArmenSl]

Summary

Follow-up to #129. End-user documentation across BESSER could be significantly improved in format, structure, and discoverability. This issue proposes a concrete plan to address it, and raises an open question about whether to consolidate the BESSER and Web Modeling Editor (WME) docs sites.

Why now

• Improve documentation targeting end-users  #129 already captures the high-level concern (end-user docs are weak; cf. the Reddit thread referenced there).
• Extending the Auto-Generated code #477 is a concrete example of the gap: a user starting a real project (Backend Generator + REST API + DB) could not find guidance on how to extend generated code (auth, middleware, custom endpoints) — a perfectly reasonable end-user need that the docs don't address.
• The recent contributor-side cleanup (CONTRIBUTING.md, docs/source/contributor_guide.rst) makes the gap on the user-facing side more obvious by contrast.

Observed gaps

1. Two separate docs sites. Backend/metamodel/generator docs live at https://besser.readthedocs.io, WME docs live at https://besser.readthedocs.io/projects/besser-web-modeling-editor/. Users hitting the main site rarely discover the WME guides, and vice versa.
2. Generator pages are reference-style, not task-oriented. A user who wants to extend generated code, plug in auth, add custom routes, or customize templates has to reverse-engineer it (Extending the Auto-Generated code #477).
3. Few end-to-end tutorials. "I have an idea → I built and deployed something with BESSER" walkthroughs are scarce; most pages document APIs in isolation.
4. Visual inconsistency. Some pages are dense walls of text; others use admonitions, tables, screenshots. Navigation depth and TOC structure vary by section.
5. Search is unhelpful. Many concepts (e.g., "extend generator output", "add middleware", "custom template") return nothing useful.
6. Examples scattered. Examples live across docs/source/, the BESSER-examples repo, and tests/. There is no single index.

Open question — consolidate the docs sites?

Currently:

• Main BESSER docs: backend, metamodel, generators, utilities, contributor guide.
• WME docs (separate Sphinx project): editor UI, diagram-type guides, frontend contributor guide.

Options:

• A. Keep them split (current). Pro: each repo stays self-contained. Con: poor cross-discovery, duplicated landing pages, users do not know where to look.
• B. Merge both into the main BESSER site (one Sphinx tree, with WME content imported via the submodule or intersphinx). Pro: one search, one TOC, one mental model for end users. Con: extra build complexity; the WME repo loses its standalone docs.
• C. Keep them split, but cross-link aggressively (shared landing page, prominent "are you a modeler / contributor / integrator?" routing on both sides, intersphinx between the two). Pro: cheaper than B. Con: still two sites.

I lean toward C as a pragmatic first step and B as the long-term direction, but this should be discussed before any restructuring work starts.

Proposed scope (incremental)

Phase 1 — low-risk format & navigation cleanup:

• Add a clear "audience" landing page on the main docs site: modeler, integrator/extender, contributor.
• Standardize page structure: every reference page starts with What it is, When to use, Quick example, then API details.
• Add admonitions consistently (.. note::, .. warning::, .. tip::) instead of inline bold paragraphs.
• Add a top-level "Examples" index that links to docs/source/, tests/, and BESSER-examples in one place.
• Cross-link the two Sphinx sites (intersphinx mapping in both directions).

Phase 2 — content gaps:

• End-to-end tutorial: "From class diagram to deployed FastAPI + DB in 10 minutes".
• "Extending generated code" guide that closes Extending the Auto-Generated code #477 (auth, middleware, custom routes, custom templates, override hooks).
• Per-generator "customization" page (which templates exist, which fields are configurable, how to override).
• WME end-user guide: typical workflows, not just diagram-type reference.

Phase 3 — consolidation decision (option A/B/C above):

• Decide the long-term structure based on Phase 1+2 experience.
• If merging: plan submodule-aware Sphinx build, redirect old URLs.

Related

• Improve documentation targeting end-users  #129 — parent issue: improve docs targeting end-users
• Extending the Auto-Generated code #477 — concrete documentation gap (extending generated code)
• Update documentation for python version #408 (closed) — Python version doc update (precedent for keeping docs in sync)
• Unreadable diagram #472 (closed) — unreadable diagram (visual-quality precedent)

Asks

• Feedback on the consolidation direction (A vs B vs C).
• Owners for Phase 1 items — most are mechanical and could be split into docs/ PRs.