Three more insights from Use Cases, then reorder and retitle the series

[oblomov-dev]

Follow-up to #204. Three commits.

Three articles from the Use Cases page, and the page removed

advanced/use_cases.md is cut into one claim each, reusing the six diagrams it already ships rather than drawing new ones:

• New #19 When the API Is Not Released — the four clean core levels as a table, and the wrapper as the move when the API you need is not released. It ends on why that is worth doing: a wrapper does not make the dependency clean, it makes it findable. Kept off update #18's ground — update #18 asks whether an app is cloud-ready, New #19 asks what to do when the API is not.
• New #20 On-Stack or Side-by-Side — lifecycles rather than code, with the cost stated plainly: a remote call is slower, the released remote APIs are narrower than a local SELECT, and there is a second system to run.
• Tree #21 One App, Many Systems — the SaaS shape, resting on what earlier articles established. Its limits paragraph names the genuinely new one: with several customers behind one app, the tenant boundary is the app's job.

The page is removed only after those three carry what it held — the level table, the note that nothing written under the three-tier model has to be migrated, SAP's own sources, and all six diagrams; three were still unused and the deletion would have orphaned them. about.md points at the two articles instead.

Numbered sidebar, and the comparison tables back

The sidebar reads #1 … to #28 …, generated from the file prefix so it cannot drift.

Articles 26–28 lost their tables when the source pages were cut into prose. They are back, built from the architecture rows of the old technology/rap.md, ui5.md and low_code.md: backend, frontend, UI definition, data model, communication, deployment. The verdict rows those pages also had — Learning Curve, Use Case Fit, the tick-and-cross columns — stay out: a table that scores one side against the other says less than the two recommendation paragraphs each article already ends on, and ages worse.

Reading all 28 in order

The order had grown by accretion. The limits article sat at 19 with nine articles after it, though it is written as a closer. The two clean-core articles were six apart. And the neutral "Where the View Lives" was separated from the three when-to-use-which articles it introduces. The arc now runs: what it is (1–4), how it works (5–13), what it is like to work with (14–16), where it runs (17–21), how much of it you have to trust (22), where it sits historically (23), what it cannot do (24), which to choose (25–28). Limits immediately before the decisions is where that article earns its keep. Free to do now and only now — nothing past #1 is published.

Four titles were wrong, not merely weak:

was	now	why
One Service for Every App	The Same Service for Every App	read as one service per app, the opposite of the point
Twenty-Five Years of ABAP on the Web	From ITS to abap2UI5	ITS 2000 to abap2UI5 2023 is 23, and the number would rot every January
Where the Line Is	What It Does Not Do	third "Where …" title, and it said nothing
The Frontend That Does Not Know What It Shows	The Frontend Knows Nothing	wrapped to three lines in the sidebar

Two leftovers went with them: article 1 still carried "scheduled for Tuesday, 25 August 2026" from its drafting, on a published page; and the limits article opened by counting the articles before it, which breaks every time the series grows.

Gates

All nine green locally except check:samples, which fails only against a stale sibling abap2UI5/samples checkout here — CI checks out samples@main and it passed on #204.

Renumbering broke the two links about.md had into the series; docs:build caught them, which is exactly the failure mode that gate exists for.

🤖 Generated with Claude Code

https://claude.ai/code/session_01N5aUUqLaxN6kxKxsHhuicp

---

Generated by Claude Code

[Copilot]

🟡 Changes recommended

The PR description claims the numbered sidebar is generated from file prefixes to prevent drift, but the sidebar numbering is still manually hard-coded in config.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refactors and extends the “Technical Insights” documentation series by extracting the former Use Cases page into dedicated numbered articles, restoring comparison tables in the “when to use which” articles, and updating navigation and cross-links to match the new structure.

Changes:

• Split advanced/use_cases.md into three new insight articles (#19–#21) and remove the original page.
• Reorder/retitle the insights series and update the VitePress sidebar to show #1…#28.
• Restore architecture comparison tables in articles #26–#28 and update related headings/teasers.

File summaries

File	Description
docs/get_started/about.md	Updates the “deployment scenarios” pointer to the new insights articles instead of the removed Use Cases page.
docs/advanced/use_cases.md	Removes the old Use Cases page after content is split into dedicated articles.
docs/advanced/insights/28-low-code-or-abap2ui5.md	Reintroduces the Low-code vs abap2UI5 comparison table.
docs/advanced/insights/27-freestyle-or-abap2ui5.md	Reintroduces the UI5 Freestyle vs abap2UI5 comparison table.
docs/advanced/insights/26-rap-or-abap2ui5.md	Reintroduces the RAP vs abap2UI5 comparison table.
docs/advanced/insights/25-where-the-view-lives.md	Adds the “Where the View Lives” bridging article and diagram.
docs/advanced/insights/24-where-the-line-is.md	Retitles/reframes the “limits” article (“What It Does Not Do”).
docs/advanced/insights/23-abap-on-the-web.md	Retitles the historical context article (“From ITS to abap2UI5”).
docs/advanced/insights/22-2300-lines.md	Adds the “2,300 Lines” footprint/auditability article.
docs/advanced/insights/21-one-app-many-systems.md	Adds the “One App, Many Systems” (SaaS shape/tenant boundary) article.
docs/advanced/insights/20-on-stack-or-side-by-side.md	Adds the lifecycle-focused on-stack vs side-by-side article.
docs/advanced/insights/19-when-the-api-is-not-released.md	Adds the clean-core levels + wrapper pattern article.
docs/advanced/insights/18-cloud-ready-is-a-property-of-your-app.md	Adds the “cloud-ready depends on what your app reads/writes” article.
docs/advanced/insights/07-one-service-for-every-app.md	Retitles article #7 to remove ambiguity (“The Same Service for Every App”).
docs/advanced/insights/06-the-frontend-that-does-not-know.md	Retitles article #6 for a shorter sidebar-friendly title (“The Frontend Knows Nothing”).
docs/advanced/insights/01-somewhere-on-the-way-to-ui5.md	Removes a future-dated drafting note from a published page.
docs/.vitepress/config.mjs	Updates sidebar order/titles and removes the Use Cases entry; adds #n prefixes in the sidebar labels.
blog/teaser-posts.md	Keeps teaser headings aligned with the retitled articles.

Review details

• Files reviewed: 15/18 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.