[
https://issues.apache.org/jira/browse/CAMEL-23806?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18090373#comment-18090373
]
Claus Ibsen commented on CAMEL-23806:
-------------------------------------
While working on splitting large doc pages, we found that many AWS (and Azure)
component docs have highly repetitive producer operation examples. Each
operation gets a near-identical Java/XML/YAML tab block that differs only in
the operation= parameter name — inflating pages by 1000+ lines of boilerplate.
The fix is to condense these into: (1) a single "common pattern" example
showing the general approach, (2) an operations reference table listing all
operations with descriptions, and (3) detailed examples only for operations
with genuinely unique patterns (e.g. copyObject with destination headers,
presigned URLs, Glacier restore, page blob ranges, etc.).
This was already done for aws2-s3 and azure-storage-blob. The following
components likely need the same treatment:
- camel-aws2-iam (1,365 lines)
- Other AWS components with operation-based producers (aws2-ses, aws2-sns,
aws2-sqs, aws2-ec2, aws2-ecs, aws2-eks, aws2-kms, aws2-msk, aws2-sts, etc.)
- camel-google-firestore (1,177 lines)
- camel-mongodb (1,323 lines)
Pattern to look for: if a doc page has more than ~5 tab blocks that only differ
in the operation parameter, it should be condensed.
> Split long documentation pages into focused sub-pages
> -----------------------------------------------------
>
> Key: CAMEL-23806
> URL: https://issues.apache.org/jira/browse/CAMEL-23806
> Project: Camel
> Issue Type: Improvement
> Components: documentation
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.21.0
>
>
> h2. Problem
> Several documentation pages are very long (2,000-5,700 lines), making them
> hard to navigate and overwhelming for users. We have received negative
> feedback about this.
> h2. Longest Pages
> ||Page||Lines||Content Type||
> |keycloak-component|5,705|95% prose/examples|
> |pqc-component|3,307|95% prose|
> |mina-sftp-component|3,175|90% prose/config|
> |simple-language|2,836|70% prose, 30% tables|
> |salesforce-component|2,546|60% tables, 40% prose|
> |rest-dsl|1,741|40% code examples|
> |exception-clause|1,651|45% code examples|
> h2. Redundant Examples
> keycloak-component and pqc-component have paired Java/YAML code examples for
> every single operation, which inflates the pages enormously. Most operations
> follow the same pattern so a few representative examples plus a reference
> table of operations would be far more effective than exhaustive examples for
> each one. This alone could cut those pages in half before splitting into
> sub-pages.
> h2. Suggested Splits
> h3. keycloak-component (5,705 lines)
> First reduce by removing redundant per-operation examples (keep a few
> representative ones, add a reference table for the rest). Then split:
> * *keycloak-producer* - Producer operations
> (realm/user/role/client/group/session/token)
> * *keycloak-consumer* - Consumer event processing
> * *keycloak-security-policies* - Authorization, token introspection, caching
> * Keep main page as overview with URI format, options tables, and links
> h3. pqc-component (3,307 lines)
> First reduce redundant per-algorithm examples (most follow the same pattern).
> Then split:
> * *pqc-key-lifecycle* - Key lifecycle management, rotation, export/import
> * *pqc-hybrid-cryptography* - Hybrid signature/KEM operations
> * *pqc-dataformat* - PQC DataFormat usage
> * Keep main page for signature/verification basics and algorithm overview
> h3. mina-sftp-component (3,175 lines)
> * *mina-sftp-authentication* - All authentication methods
> * *mina-sftp-security* - Ciphers, key exchange, host keys, algorithm
> recommendations
> * *mina-sftp-migration* - Migration from JSch
> * Keep main page for basic usage, URI format, options, examples
> h3. simple-language (2,836 lines)
> * *simple-functions* - All function reference tables grouped by category
> * *simple-operators* - Comparison, numeric, boolean operators
> * *simple-ognl* - OGNL expression support (requires extra JAR)
> * *simple-advanced* - Init blocks, custom functions, JavaScript validator
> * Keep main page as quick intro with examples and links
> h3. salesforce-component (2,546 lines)
> * *salesforce-rest-api* - CRUD, query, composite operations
> * *salesforce-bulk-api* - Bulk 2.0 and original bulk API
> * *salesforce-streaming* - Pub/Sub and Streaming API
> * Keep main page for getting started, auth, common usage
> h3. rest-dsl (1,741 lines)
> * *rest-dsl-binding* - POJO binding, Jackson config, CORS
> * *rest-dsl-validation* - Request/response validation
> * *rest-dsl-openapi* - OpenAPI/Swagger integration
> h3. exception-clause (1,651 lines)
> * *exception-redelivery* - Redelivery policy and configuration
> * *exception-handling-patterns* - Handled vs continued, original message
> * *exception-advanced* - Global vs route-specific, onWhen, retryWhile, custom
> strategies
> h2. General Approach
> Each main page should become an overview/landing page (under 500 lines) with:
> * Quick introduction and basic usage
> * Auto-generated options tables
> * Links to focused sub-pages for detailed topics
> Sub-pages should be self-contained and cross-linked. The goal is that no
> single page exceeds roughly 1,500 lines.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
