It would be great to do this IMO, because there are often usability and formatting fixes needed to docs over time, and people naturally search for docs from their *deployed* version of the project — not the latest version, hoping that it also applies to their release.
For example, right now there’s a bug where the language switcher for code examples on many versions of our docs does not toggle all the code examples on the page. If you switch one example from Scala to Python, it used to switch all the other ones too, but it stopped doing that. It would be great to fix this. There may be smaller issues too. > On Aug 30, 2023, at 10:27 PM, Hyukjin Kwon <gurwls...@apache.org> wrote: > > Hi all, > > I would like to raise a discussion about updating documentation hosted for > EOL and maintenance > versions. > > To provide some context, we currently host the documentation for EOL versions > of Apache Spark, > which can be found at links like > https://spark.apache.org/docs/2.3.1/api/python/index.html. Some > of their documentation appear in search results on the top if you google. The > same applies to > maintenance releases. Once technical mistakes in the documentation, incorrect > information, > etc. are landed mistakenly, they become permanent and/or cannot easily be > fixed, e.g., until > the next maintenance release. > > In practice, we’ve already taken steps to update and fix the documentation > for these EOL and > maintenance releases, including: > > Algolia and Docsearch in which we require to make some changes after > individual release > for allowing search results in Apache Spark website and documentation > Regenerating the documentation that was incorrectly generated. > Fixing the malformed download page > … > I would like to take a step further, and want for the doc changes of > improvement and better examples, > in maintenance branches, to be landed to the hosted documentation for better > usability. > The changes landed into EOL or maintenance branches, according to SemVer, are > usually only bug > fixes, so the documentation changes such as fixing examples would not > introduce any surprises. > > Those documentation are critical to the end users, and this is the very one I > heard most often > where we should improve, and I eagerly would like to improve the usability > here. > > TL;DR, what I would like to propose is to improve our current practice of > landing updates in the > documentation hosted for EOL and maintenance versions so that we can show a > better search > result for Spark documentation, end users can read the correct information in > the versions they use, > and follow the better examples provided in Spark documentation. > > >
