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
