> I probably would probably avoid trying to emulate Google Android docs / > Apple docs, which is effectively powered by documenting code via > javadoc or whatever.
The goal is not to exactly emulate Google or Apple. Instead, the intent is to standardize the formatting of pages and content to include platform versions of which something was added or deprecated. For example API-driven pages, such as the Config and Plugin XML API references. These pages list various preferences, and I propose that we include the platform version in which each preference was added or deprecated. For example, the "GradleVersion" preference. We should display the version in which the preference was introduced: Cordova-Android: 10.0 If it later becomes deprecated, it should instead be shown as: Cordova-Android: 10.0–20.0 Deprecated > Instead we should continue to format our documentation in more of a > "guide" style format, which is effectively what we do already. I'm not saying we should stop writing the documentation in a “guide” style. Rather, the idea is that the documentation should include a widget or indicator that clearly shows which platforms and versions each feature is supported on. For example, we might have had a section explaining when and how to use WebSQL. That content was likely written in a guide style, but at the top of the section we could have displayed something like “Supported in …”. Now that WebSQL has been deprecated on various platforms, we could update that support indicator to reflect the deprecation. Another thing to note is that we didn't add any logic to support WebSQL, as it was a core feature of the WebViews. However, because we documented in our guides, we could still provide a "supported in" range for it. Or, we just flag this content to be removed in a later cleanup process. The content itself would continue to be written as a guide. > 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. When I said to remove “snapshot,” I was referring to removing the feature that lets us splice in new versions or update existing versions and then present multiple documentation versions in a dropdown for users to select and view. And with the current snapshots system, it would rebuild on every deployment of the site. I personally think basing the docs around a CLI version is confusing, because much of the documentation is platform-based. Platform versions are no longer tied to a specific CLI release. For example, Cordova-CLI 12.x is more than three years old, yet there have been many Android and iOS platform releases since then. We can keep the snapshot concept, but it would work differently. It should essentially generate an offline version of the docs that gets moved to the archive section. The archive would not be part of the live documentation. The end goal is to have one live documentation version and remove the version dropdown entirely. > Documenting (and deprecating) plugins is another challenge. Are those > still automatically generated from a doc folder in each plugin repo? The plugin documentation is pulled from each plugin’s repository. The content is taken directly from the plugin’s README.md, not from a doc directory. The Cordova CLI command documentation also comes from the CLI repository, and its content is sourced from doc/readme.md. Hopefully this clears up any confusion about what I was suggesting. On Tue, Nov 25, 2025 at 1:09 PM Darryl Pogue <[email protected]> wrote: > 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] > >
