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]
