[
https://issues.apache.org/jira/browse/CAMEL-23806?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen reassigned CAMEL-23806:
-----------------------------------
Assignee: Claus Ibsen
> 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)
