Hi Bryan, thanks for your discussion mail.
Since cordova-android and cordova-ios releases are mostly independent from cordova-cli releases, we should not use the cordova-cli version to categorize the documentation. I like the idea to have only one recent documentation. The documentation could clarify if a minimum cordova-cli version is needed for something. Regarding URL Refactoring, I would suggest https://cordova.apache.org/documentation. It’s a good idea to support only English as main documentation language and remove „en“ from the url. Regards, Manuel Von: Bryan Ellis <[email protected]> Datum: Montag, 24. November 2025 um 09:11 An: [email protected] <[email protected]> Betreff: [DISCUSS] Improving Cordova Documentation and Versioning Hello all, I would like to start a discussion on how we can better present our documentation and reduce confusion around versioning. Below are the main points I'd like to raise, get feedback on, and potentially put to a vote. ========== 1. Deprecate and Archive Past Versions - All past version documentation should be deprecated and moved to an archive section. - This will help users focus on the current, maintained documentation and reduce confusion about outdated information. ========== 1. Remove Snapshot Logic - Only provide the current, stable documentation. - Refactor documentation to include tags indicating when features or preferences were added or deprecated. Examples and Suggestions: - Config Preference Pages: - Could be refactored to organize content into sections per configuration, rather than large tables. - If tables are kept, add a column to show "Cordova Support" for each entry. - The idea is to emulate documentation standards from Apple or Google: - E.g. Apple WebKit WKProcessPool: https://developer.apple.com/documentation/webkit/wkprocesspool - E.g. Android WebView.capturePicture: https://developer.android.com/reference/android/webkit/WebView#capturePicture/ Example display for version support: iOS: 8.0+ iOS: 4.1–8.0 (Deprecated) Another note: - Should discuss at what point would it be removed from the docs altogether? - Perhaps the configuration settings and other API documentation could be structured in YAML format. ========== 1. Use Staging Environment - Start using a staging environment to preview changes to both the docs and website. - This allows review and testing before publishing live updates. - Current snapshots only focused on docs. - This would also be the replacement of dev docs. The proposed staging workflow is as follows: create and push changes to a development branch. This branch will be built and deployed to a staging branch, which is served on the staging domain. Once development is complete, the dev branch is rebased into the main branch, which is then built and deployed to the official site. Main branch could also be protected and only PRs are valid ways to update the live site. ========== Other Proposed Changes URL Refactoring: - If we only present the latest documentation, the URL pattern can be simplified. - Current URL pattern: https://cordova.apache.org/docs/en/latest/ - Proposed simplification: https://cordova.apache.org/docs/ - Notes: - Rewrite rules may require a complete new URL structure. - Options: drop the "s" in "docs" (/doc/) or spell it out as /documentation/. Or something else... - Redirects: - /docs or /docs/en/latest/ → redirect to new documentation. - /docs/en/{VERSION}/ → redirect to /archive/docs/en/{VERSION}. - /docs/en/dev/ → would be dropped. ========== Language Documentation: Reiterating: the current URL pattern suggests that documentation is available in other languages. - All Language docs were already deprecated and archived. Reason why: - Language-specific docs were poorly maintained and lacked expertise. - Expect users to use browser translation or third-party translation services. This is why language should also be removed from the URL pattern. ========== Summary - Archive past versions. - Remove snapshot logic and focus on current documentation with clear version tags. - Use a staging environment for previews. - Simplify URLs and redirects to improve user experience. - Better structure API data from visual. Regards, Bryan
