Backstory for newer folks: The docs are organized by CLI version because the platform versions used to be pinned to a particular CLI version. Once upon a time there was a goal to release all the cordova packages on a weekly basis. That never actually worked in practice due to release voting timelines, and then the platform pinning stopped being true a few years ago... and now the version-based organization of the docs doesn't quite make sense with different platform, plugin, and tooling versions. Unfortunately, I don't have any particularly good ideas for how to structure things better so that the platform versions are more obvious.
We don't really want to introduce separate per-platform documentation though. The goal is that you can follow the docs and get your project working with any of the supported platforms, with maybe a platform-specific page listing the special considerations for that platform (Android Studio stuff, Xcode and codesigning stuff, etc.). I don't think Javadoc/DocC are a good fit for general documentation intended for CLI users and app developers, but I do like having them available for plugin developers and other Cordova contributors. I've been trying to build out the DocC documentation on the iOS side. I think we should try to keep the history that we have intact, but ideally as an HTML snapshot rather than as something that gets rebuilt every time. I think we already have something like this for old versions and old translations? "Cool URIs don't change" and all. Norman is right about the preferences being a particularly awkward area, because those all live on the config.xml page right now (with a bunch of other non-preference info) and yet those are something that often depend on particular platform versions. Documenting (and deprecating) plugins is another challenge. Are those still automatically generated from a doc folder in each plugin repo? ~Darryl On Mon, Nov 24, 2025 at 12:19 PM Norman Breau via dev <[email protected]> wrote: > > I probably would probably avoid trying to emulate Google Android docs / > Apple docs, which is effectively powered by documenting code via > javadoc or whatever. I think it is definitely worth to have separate > API reference sites for these style of documentation but out of scope > for this particular discussion. > > Instead we should continue to format our documentation in more of a > "guide" style format, which is effectively what we do already. I do > agree that some parts though are formatted poorly and perhaps hard to > digest. Speaking on the preferences and this is from a support > perspective... one of the pain points is the lack of hyperlinks. Often > I want to point the user to a particular preference but the table > doesn't naturally offer an anchor point. > > On the snapshot removal... > > I think there is a certain value of record keeping. So I think we need > to have some kind of archival strategy where old docs are viewable. Do > I think we need to continue with our current snapshot strategy? No, > maybe not. > > I think there is a balance to be found. Documentation doesn't need to > be completely immutable... I think a document can be updated and we > don't need to snapshot every mutation. But unless if there is very good > reason, documentation should be archived rather than completely deleted > whenever possible. Lets take `cordova-windows` for example. If we are > deprecating `cordova-windows`, all documentation related to cordova- > windows should probably be archived so that users who wants or still > has a need to use cordova-windows simply because they are maintaining > legacy software (and accept the responsibilities associated with legacy > software) they still have access to a reference of related > documentation, even if they are not prominent on the main pages. > Hopefully this makes sense. > > On Mon, 2025-11-24 at 18:16 +0000, [email protected] wrote: > > 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 > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
