Rework the Technical Insights series: fixes, merges, index page, twelve new articles

[oblomov-dev]

A review of the 28-article series under Advanced Topics, applied in full: what was wrong, what was said twice, what an ABAP developer would look for and not find.

Fixes

• #1 rendered two literal *[image: …]* placeholders as italic text. They are replaced by a design-time versus runtime diagram (01-runtime-model.svg).
• update #9 PUBLIC Means Persisted contradicted the Cookbook's Life Cycle page. The whole instance is serialized regardless of visibility, PUBLIC is what _bind( ) needs to reach an attribute, and the browser carries a draft id, never the state. Rewritten as update #9 A New Instance on Every Request around that.
• update #12 named z2ui5_if_exit, deprecated since 1.144.0 — now z2ui5_if_ui5_exit, with a link to the user-exit page. custom_js verified against the interface on main.
• Claude/fix string delimiters  #32 From ITS to abap2UI5 (was update model etc #23) had shaky years: ITS 1996, Web Dynpro ABAP 2006, UI5 2012. Text and timeline diagram corrected.
• #5 carried the "this article and the ones that follow it are cut from Under the Hood" footnote from before the reorder; the source note moved to the index page.
• Test #8's example used an undeclared partly variable; the example is now self-contained.

Structure

• Index page docs/advanced/insights/index.md: the axis diagram from the former make user exits visible #25 plus four blocks (Why, How It Works, A Working Day, Where It Belongs) with a one-line teaser per article. The sidebar group links to it.
• Merged what was said twice: update #11 + update #16 → No Build, No Deploy, No Cache; fix dead link #7 + Update odata.md #22 → One Handler for Every App; the edges from add user exit #24 → UI5 Freestyle or abap2UI5?.
• Retitled: Update faq.md #2 in title case, Four Verbs, Every Control, A Classrun for the Browser, and the three "— When to Use Which" titles shortened to a question.
• Slugs, diagram file names and article numbers match again after the earlier reorder. Two closing aphorisms that were pathos rather than a rule are gone (update #14, Claude/fix string delimiters  #32).

New articles — a working day

Facts drawn from the corresponding Cookbook pages, each with a short snippet and a link there:

#16 One Click, One Request	roundtrip, main( ) dispatch, init before navigated
#17 What the Client Can Do	z2ui5_if_client by shape
#18 CALL SCREEN, LEAVE SCREEN	app stack, sub-apps, popups
#19 Where F4 Went	value help in three sizes
#20 MESSAGE Still Works	messages, escaping exceptions, translation
#21 The Lock Is Gone by the Next Click	enqueue in a stateless app
#22 Who May Start Which App	one ICF node, AUTHORITY-CHECK, CSRF, CSP
#23 100 Rows, Four Hours, One Request	size limit, draft expiry, cost of a click
#24 ABAP Unit for a Screen	complete class plus test class
#25 When One Class Is Not Enough	the seams of a larger app
#26 A Tile Like Any Other	Fiori Launchpad
#36 Written for Agents	the consequence of code-first

Diagrams

05-two-strings now shows the event going back. New SVGs for #1, #12, #15, #16, #21, #23, #25, all from blog/assets/make-diagrams.py; the "1 / 2 / 1" footprint diagram went with the merge. Files renumbered to the articles that show them.

Housekeeping

• docs/get_started/about.md links and blog/teaser-posts.md headings follow the new numbers and titles.
• AGENTS.md playground figures were already stale before this change (said 68/47/21, gate printed 81/62/19); they now carry the gate's current 82/63/19 — the one added complete class is add user exit #24's.

Verification

npm run check passes all nine gates locally (check:samples skips without a samples checkout, as designed). check:examples compiles the new #24 class and lints its view.

Worth knowing before merging

• URLs change from update #16 onwards and for five renamed slugs. The series was published today; any LinkedIn post already pointing at an article past update #15 needs its link updated. Teasers for the twelve new articles are not written yet.
• The six use-case SVGs in Fix typos in technical documentation #29–Claude/fix string delimiters 01 pg dbd wn gzwuma jge ubnmbi #31 keep their own, larger visual style; unchanged on purpose.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TNcDPWLbWy75RmRDeeZm7P

---

Generated by Claude Code

[Copilot]

🟢 Approval recommended

The changes are internally consistent (links, slugs, sidebar wiring, and diagram references) and no concrete build- or navigation-breaking issues were found in the reviewed diffs.

Pull request overview

This pull request restructures and refreshes the “Technical Insights” documentation series under Advanced Topics, aligning article numbering/slugs, adding an index page, merging/rewriting selected articles, and introducing new “working day” articles with updated supporting diagrams.

Changes:

• Adds a new series index page and rewires the sidebar group to point to it, with updated titles and links across the series.
• Introduces multiple new Technical Insights articles (#16–#26 and #36) and updates/retitles existing comparison articles (#33–#35).
• Adds/renumbers/updates SVG diagrams and updates diagram generation logic and references accordingly.

File summaries

File	Description
docs/public/insights/32-timeline.svg	Updates the timeline diagram content (corrected years).
docs/public/insights/28-vdm.svg	Adds the renumbered VDM diagram used by #28.
docs/public/insights/27-bootstrap.svg	Adds the renumbered UI5 bootstrap diagram used by #27.
docs/public/insights/25-more-than-one-class.svg	Adds the “more than one class” diagram used by #25.
docs/public/insights/23-what-a-click-costs.svg	Adds the “what a click costs” diagram used by #23.
docs/public/insights/21-lock-at-save.svg	Adds the lock-at-save diagram used by #21.
docs/public/insights/18-footprint.svg	Removes the footprint diagram (content merged elsewhere).
docs/public/insights/16-dispatch.svg	Adds the dispatch/branching diagram used by #16.
docs/public/insights/15-parameters-bind.svg	Adds the PARAMETERS vs OData vs _bind diagram used by #15.
docs/public/insights/12-three-seams.svg	Adds the “three seams” diagram used by #12.
docs/public/insights/05-two-strings.svg	Updates the “over-the-wire” diagram to show event roundtrip.
docs/public/insights/01-runtime-model.svg	Adds the design-time vs runtime model diagram used by #1.
docs/public/insights/00-where-the-view-lives.svg	Adds the axis/index diagram for the series index page.
docs/get_started/about.md	Updates links to the renumbered deployment-scenario insights articles.
docs/advanced/insights/index.md	Adds the new Technical Insights index page with grouped lists and the axis diagram.
docs/advanced/insights/36-written-for-agents.md	Adds new article #36 describing agent-related consequences and supporting site artifacts.
docs/advanced/insights/35-low-code-or-abap2ui5.md	Renumbers/retitles #35 and updates heading accordingly.
docs/advanced/insights/34-freestyle-or-abap2ui5.md	Renumbers/retitles #34 and expands the “edges” section as bullets.
docs/advanced/insights/33-rap-or-abap2ui5.md	Renumbers/retitles #33 and updates heading accordingly.
docs/advanced/insights/32-from-its-to-abap2ui5.md	Renumbers #32, corrects years, updates diagram reference and narrative.
docs/advanced/insights/31-one-app-many-systems.md	Renumbers #31 and updates heading accordingly.
docs/advanced/insights/30-on-stack-or-side-by-side.md	Renumbers #30 and updates heading accordingly.
docs/advanced/insights/29-when-the-api-is-not-released.md	Renumbers #29 and updates heading accordingly.
docs/advanced/insights/28-cloud-ready-is-a-property-of-your-app.md	Renumbers #28 and updates the diagram reference to /insights/28-vdm.svg.
docs/advanced/insights/27-one-codebase-702-to-abap-cloud.md	Renumbers #27 and updates the diagram reference to /insights/27-bootstrap.svg.
docs/advanced/insights/26-a-tile-like-any-other.md	Adds new article #26 about Launchpad tiles and integration.
docs/advanced/insights/25-where-the-view-lives.md	Removes prior standalone article (content moved to index/other structure).
docs/advanced/insights/25-when-one-class-is-not-enough.md	Adds new article #25 describing multi-class seams and references new diagram.
docs/advanced/insights/24-where-the-line-is.md	Removes prior standalone “What It Does Not Do” article (content incorporated elsewhere).
docs/advanced/insights/24-abap-unit-for-a-screen.md	Adds new article #24 with an ABAP Unit example and testing guidance.
docs/advanced/insights/23-100-rows-four-hours-one-request.md	Adds new article #23 covering performance-related “three numbers” and references new diagram.
docs/advanced/insights/22-who-may-start-which-app.md	Adds new article #22 covering authn/authz, CSRF, CSP concepts and example handler checks.
docs/advanced/insights/22-2300-lines.md	Removes prior standalone “2,300 Lines” article (content merged into #7).
docs/advanced/insights/21-the-lock-is-gone-by-the-next-click.md	Adds new article #21 about locking strategies in stateless apps and references new diagram.
docs/advanced/insights/20-message-still-works.md	Adds new article #20 about messages/exceptions and production error-detail hiding.
docs/advanced/insights/19-where-f4-went.md	Adds new article #19 about value help patterns in abap2UI5.
docs/advanced/insights/18-call-screen-leave-screen.md	Adds new article #18 about the app stack, sub-apps, popups, and navigation.
docs/advanced/insights/17-what-the-client-can-do.md	Adds new article #17 describing the z2ui5_if_client surface “by shape”.
docs/advanced/insights/16-one-click-one-request.md	Adds new article #16 explaining the request/click mental model and dispatching.
docs/advanced/insights/16-no-cache-no-deploy-any-ide.md	Removes prior standalone article (merged into #11).
docs/advanced/insights/15-where-the-selection-screen-went.md	Adds a new diagram + caption illustrating PARAMETERS/OData/_bind.
docs/advanced/insights/14-a-classrun-for-the-browser.md	Retitles/rewrites parts of #14 and links forward to the new #25.
docs/advanced/insights/13-four-verbs-every-control.md	Retitles #13 to “Four Verbs, Every Control”.
docs/advanced/insights/12-where-your-own-javascript-goes.md	Adds a new diagram + caption and updates the interface name/link for user exits.
docs/advanced/insights/11-no-build-no-deploy-no-cache.md	Adds merged article #11 combining prior “No cache/deploy” + “index.html string” content.
docs/advanced/insights/11-index-html-lives-in-a-string.md	Removes prior standalone article (merged into #11).
docs/advanced/insights/09-public-means-persisted.md	Removes prior standalone article (replaced by rewritten #9).
docs/advanced/insights/09-a-new-instance-on-every-request.md	Adds rewritten #9 clarifying instance serialization and _bind visibility needs.
docs/advanced/insights/08-only-the-changed-part.md	Fixes the previously undeclared variable in the example and clarifies model-only updates.
docs/advanced/insights/07-one-handler-for-every-app.md	Retitles #7 and merges “2,300 lines” content as a new section.
docs/advanced/insights/06-the-frontend-knows-nothing.md	Adds new article #6 describing the shell/HDA model and consequences.
docs/advanced/insights/05-ui5-over-the-wire.md	Updates diagram captioning and removes the outdated source-note footnote.
docs/advanced/insights/02-not-a-programming-model.md	Adjusts title casing in #2 heading.
docs/advanced/insights/01-somewhere-on-the-way-to-ui5.md	Replaces placeholder image text with a real diagram and caption.
docs/.vitepress/config.mjs	Updates sidebar group link and the full set of titles/links to match renumbered series structure.
blog/teaser-posts.md	Updates teaser headings to match the new titles.
blog/assets/make-diagrams.py	Renumbers and expands diagram generation to match the new article/asset mapping.
AGENTS.md	Updates the documented playground figures to match current gate output.

Review details

• Files reviewed: 44/59 changed files
• Comments generated: 0
• Review effort level: Lite

---

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