istio.io
istio.io copied to clipboard
istio
Propose: Istio old docs selection dropdown for quick and easy access
We should have Istio old docs dropdown in the sidebar (above the search box) for quick and easy access for older docs.
Currently, the user has to scroll down to footer of the docs to go to the older Istio release docs.
cc: @craigbox Is this feasible?
Two things come to mind.
Because of the way the site is archived, there's no guarantee that a particular page exists from version to version - although most will. I would expect a version dropdown to take me to that page in an older version.
Is that the right place to put it? How many people come to the site looking for documentation for older versions? I think the answer is probably "a lot", given how hard upgrades used to be, and so forth.
Perhaps we should discuss this at the next Docs WG?
The challenge I see here is design changes. The proposed idea will work fine for 1.10 and above but won't work for older designs. If the version is less than 1.10 we should open the page in a new tab else render it in the same tab.
Many people still use older versions of Istio and take some time to upgrade to a new version, so I think this feature will be useful.
Perhaps we should discuss this at the next Docs WG?
Sounds good.
We discussed at the Docs WG... as discussed!
- Right now, we generate (and apparently test) the entire site for each old version. We should really only archive the docs,and then, for an agreed number of versions - we should assume no-one is running <1.0 versions?
- There's no record of links between pages moved/renamed in other versions.
Brian pointed out what OpenShift does: click here and try changing the version drop-down to 4.7 to see it. You'll get a popup saying "This page no longer exists; would you like to search?"
This would be valuable work, but there's currently no-one assigned to docs so we can't commit to doing it. I have labelled the issue "help wanted". It would warrant a full design doc, and may also have to be prioritized vs. spending that amount of effort on improving our current documentation. At the moment we feel we've done the easy/possible thing: give a link to the previous versions of the site, in the footer.