Skip to content

Documentation improvements and consistency updates - #120

Merged
oblomov-dev merged 4 commits into
mainfrom
claude/documentation-clarity-1oqk7y
Jul 5, 2026
Merged

Documentation improvements and consistency updates#120
oblomov-dev merged 4 commits into
mainfrom
claude/documentation-clarity-1oqk7y

Conversation

@oblomov-dev

@oblomov-dev oblomov-dev commented Jul 5, 2026

Copy link
Copy Markdown
Member

This PR improves the documentation across multiple sections with better clarity, consistency, and practical guidance.

Summary

Comprehensive documentation updates focusing on:

  • Standardizing terminology and formatting (e.g., "HTML Over the Wire" → "HTML Over-the-Wire")
  • Expanding configuration guides with more detailed setup instructions
  • Improving code examples and technical explanations
  • Removing outdated LinkedIn blog post references in favor of inline documentation
  • Enhancing user guidance with clearer prerequisites and step-by-step instructions

Key Changes

Technical Documentation

  • Updated "How It All Works" guide with consistent hyphenation of "Over-the-Wire" terminology throughout
  • Improved conceptual explanations in technical sections with better context

Configuration Guides

  • Fiori Launchpad: Expanded from brief links to comprehensive inline documentation covering installation, feature detection, dynamic titles, startup parameters, and cross-app navigation with code examples
  • BTP Build Work Zone: Replaced LinkedIn blog references with detailed setup instructions for destinations, connector apps, and Work Zone content configuration
  • Mobile Start: Added complete setup workflow linking to BTP configuration
  • Authorization: Clarified service-level authorization patterns with better terminology

Cookbook & Examples

  • Tables: Renamed "Table with Filtering, Sorting" to "Table with Sorting" and updated explanation to reflect backend-driven sorting approach with view_model_update
  • Binding: Updated class names for consistency (e.g., z2ui5_cl_app_hello_world → zcl_app_hello_world)
  • SQL: Improved code structure and control flow patterns (CASE → IF/ELSEIF)
  • Lock handling: Clarified soft lock concepts and added table schema reference
  • Expression Binding: Improved section title clarity

Getting Started

  • About: Refined language comparing classic ABAP UI patterns to modern web apps
  • Quickstart: Added prerequisites for abapGit and clarified ABAP vs ABAP Cloud setup paths
  • Hello World: Improved navigation instructions to startup page
  • Full Example: Added explanation of attribute stashing pattern for handler methods

Advanced Topics

  • Renaming: Replaced blog post reference with inline explanation of abaplint downport workflow and configuration examples
  • Downporting: Added detailed explanation of automated 702 branch generation and syntax transformations
  • Agent: Reordered lifecycle checks for better logical flow
  • Fiori Integration: Clarified object page section ID placeholder

Minor Improvements

  • Fixed SQL SELECT statement formatting (WHERE before INTO)
  • Improved code example clarity in multiple sections
  • Enhanced prerequisite documentation for cross-system setups
  • Removed redundant blog post links in favor of self-contained documentation

https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH

claude added 4 commits July 4, 2026 13:58
@claude
docs: improve clarity and fix inconsistencies across all sections
7baa422 
Sweep of the whole documentation for understandability, fixing
contradictions, stale references, and unclear wording:

- get_started: resolve 7.02/7.50 release contradiction, explain the
  extensibility tiers, unify "startup page" naming, explain the NS
  operator and the empty edit-button column in the full example
- cookbook: fix wrong method/event names (bind_edit, download_b),
  correct the OData metadata-binding example (entity type name and
  sap:label value), align the soft-lock example table name, repair
  numbered-heading anchors, explain nav_app_leave's two modes and the
  $event prefix exception, remove a stray demo button, fix the EML
  double backslash
- configuration: update the outdated default CSP, clarify SAPUI5 vs
  the OpenUI5 bootstrap default, use get_form_field for the app_start
  URL parameter, neutral handler class name, clearer launchpad and
  transport guidance
- advanced/technical: fix broken clone path and name the three config
  files, align dispatcher order in agent.md with the canonical
  template, promote H5 headings in how_it_all_works so the outline
  works, consistent "Over-the-Wire" spelling and backend-system
  terminology, complete truncated code snippets

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH
@claude
docs: second clarity pass — beginner journey, code correctness, consi…
7a0bb7e 
…stency

- quickstart: state the endpoint URL (SICF Test Service), map the
  ABAP/ABAP Cloud tabs to system types, explain the Handler List step,
  how to launch your own class, abapGit prerequisite, and a naming tip
  (customer namespace vs. reserved Z2UI5_ prefix)
- hello_world/full_example: explain why bound attributes must be
  public, the me->client pattern, shell( )/get_parent( ) and
  get( )-event vs get_event_arg( ) on first use
- life_cycle: drop the false "used by every tutorial" claim and
  acknowledge the equivalent IF/ELSEIF dispatch used by the tutorials
  and samples
- snippets: replace the non-compiling "sorting/filtering" table example
  (growing_threshold, sort_property/filter_property do not exist in the
  builder or sap.m.Column) with a real backend-sorting example
- definition: fix Dialog cross-reference (Popup, not Popover) and the
  builder property naming rule (selectedkey, not selected_key)
- binding: rename example class out of the reserved framework namespace
- smaller fixes: LO→L0 template variable, misleading button label,
  Cookbook link target, ITS vs ITS Mobile, dispatch style unified
  within abap_sql page, changelog note on check_on_event status

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH
@claude
docs: fix verified technical errors from deep review
f62a527 
- formatter: read-only _bind paths have no /XX/ segment — correct the
  resolved expression-binding string and the path = abap_true note
  (verified against z2ui5_cl_core_srv_bind=>get_client_name)
- lock: reorder INTO after WHERE in the two inline optimistic-check
  SELECTs (strict ABAP SQL) to match the full source below them
- agent guide: check_on_navigated fires on return from apps called via
  nav_app_call, not from same-app popup_display popups — make both
  comments precise
- how_it_all_works: remove self-referential cross-reference in section
  16 and qualify the "2,300 lines" figure as the original core
  communication layer

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH
@claude
docs: make guide pages self-contained instead of delegating to LinkedIn
666b6ed 
The Launchpad, BTP Build Work Zone, Mobile Start, Downporting, and
Renaming pages consisted mostly of external LinkedIn article links.
Each page now carries its own guide content; the articles remain as
"Further Reading" at the bottom.

- launchpad: add Installation section and a Launchpad Features section
  covering context detection (check_launchpad_active), dynamic tile
  title (set_title_launchpad), startup parameters (t_comp_params), and
  parameterized cross-app navigation incl. back navigation — all based
  on the LP_01–LP_04 samples
- btp: explain the destination → connector app → Work Zone content
  architecture and add the Work Zone setup steps; link SAP's own
  Work Zone tutorials
- mobile_start: document the actual setup path (Work Zone content
  mirrored into Mobile Start) instead of only linking out
- downporting: describe the automated abaplint-based downport pipeline
  that generates the 702 branch
- renaming: show how the abaplint rename configuration works and that
  CI guarantees renameability; cross-link the Builder
- use_cases: demote the blog link to Further Reading

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EC2cWJafPETwcMbh3NCsgH
@oblomov-dev
oblomov-dev merged commit d068ef9 into main Jul 5, 2026
@oblomov-dev
oblomov-dev deleted the claude/documentation-clarity-1oqk7y branch July 5, 2026 11:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@oblomov-dev @claude