Claus Ibsen created CAMEL-23806:
-----------------------------------
Summary: 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
Reporter: Claus Ibsen
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)
