Infastruture required for pending 22.04 version of Serverguide

[Doug Smythies]

For the 20.04 transition of the Ubuntu Serverguide from Docbook to Discourse markup languages, the required infrastructure to eventually support multiple LTS publications at the same time was not implemented. As we now approach the 22.04 LTS release, this issue must be addressed.

How we did it on help.ubuntu.com was to always have an LTS link, which we would change on release to day from pointing to the old LTS version to the new one, accompanied by some minor edits to the overall index.html page. Typically, the new LTS Ubuntu serverguide had already been published, and worked on, for a few months before release day with the index.html page saying "Preliminary", as can be observed now for the 22.04 desktop help publication on help.ubuntu.com

Currently:
https://help.ubuntu.com/lts/ubuntu-help/index.html
is actually:
https://help.ubuntu.com/20.04/ubuntu-help/index.html

and the preliminary 22.04 is:
https://help.ubuntu.com/22.04/ubuntu-help/index.html
and on release day it will become:
https://help.ubuntu.com/lts/ubuntu-help/index.html

[Peter Matulis (petermatulis)]

Hi Doug.

See section 'versioning' in this resource:

https://discourse.ubuntu.com/t/creating-discourse-based-documentation-pages/14132

[Doug Smythies (dsmythies)]

I get this:

"Oops! That page doesn’t exist or is private."

[Peter Matulis (petermatulis)]

Interesting. Please stand by.

[Peter Matulis (petermatulis)]

Please see

https://github.com/canonical-web-and-design/maas.io/pull/569

[Peter Matulis (petermatulis)]

@Doug

It is indeed possible to create an entirely distinct set of pages for each version, where a version would be selectable via a dropdown menu. Alternatively, a single set can be used where its pages are annotated wherever there are version differences.

Is the development activity high enough to warrant a separate documentation set? If it is, then having a guide full of annotations (and possibly screenshots and code samples) may not be the way to go. You also need to consider future versions as well (or use a combination of these ideas: a "version" that covers, say, 20.04 and 22.04).

As an aside, I seem to recall backports not being done to the Server Guide, which can mislead readers. Keeping a single set would sidestep that issue.

If you choose the first option (dropdown menu) I can follow up with instructions on how to get that done.

[Doug Smythies (dsmythies)]

Peter wrote:

> It is indeed possible to create an entirely distinct
> set of pages for each version, where a version would
> be selectable via a dropdown menu. Alternatively, a
> single set can be used where its pages are annotated
> wherever there are version differences.

Thank you for your research.

> Is the development activity high enough to warrant a separate documentation set?

I do not know.

> If it is, then having a guide full of annotations (and possibly screenshots and
> code samples) may not be the way to go. You also need to consider future versions
> as well (or use a combination of these ideas: a "version" that covers, say, 20.04
> and 22.04).

> As an aside, I seem to recall backports not being done to the Server Guide,
> which can mislead readers. Keeping a single set would sidestep that issue.

Update publications of previous LTS Ubuntu Serverguides has been very infrequent.

> If you choose the first option (dropdown menu) I can follow up with
> instructions on how to get that done.

The stakeholders are the Servergguide contributors, which I think is mainly the server team. Myself, I am okay with either solution.

[Robie Basak (racb)]

> As an aside, I seem to recall backports not being done to the Server Guide, which can mislead readers. Keeping a single set would sidestep that issue.

IMHO, given the limited amount of editor attention the server guide gets currently, it would be better to annotate the specific places where it's known that there are per-LTS differences, and keep a single set active only. Otherwise the old LTS guide will just rot. Better to have something that is generally up-to-date for older LTSes with possible omissions when there's something version specific (that we can fix when asked) than have an immediately out-of-date guide for older LTSes.

I think this method is particularly applicable here because generally everything in the guide is written retrospectively.

[Robie Basak (racb)]

(but to be clear, this is just my opinion, and I'm open to doing the opposite if the sentiment is strongly the other way)

[Doug Smythies (dsmythies)]

I sent an email to the server team late last week asking for input. Got none.

O.K. I am setting the 22.04 preliminary serverguide html and pdf links to simply point to the same place as the 20.04 versions.

[Robie Basak (racb)]

Sorry Doug. I think the server team generally agreed with my comment 7 above so nobody had anything to add and so didn't comment. I've confirmed with the server team just now that this is our team opinion.

[Doug Smythies (dsmythies)]

Hi Robie: Thanks.

Please be aware that if one follows the 22.04 link (it'll be live tomorrow, I am using my test web site), they land on this:

"Welcome to the Ubuntu Server Guide! This site includes information on using Ubuntu Server for the latest LTS release, Ubuntu 20.04 LTS (Focal Fossa). For an offline version as well as versions for previous releases see below."

I am saying it is going to need some work to de-specify exact LTS versions.
This was trivial with the doc book version, and per LTS publications. All we would do is change the master version and name definitions in an overall .XML file and they would automatically be propagated during document compile time.

[Robie Basak (racb)]

On Thu, Feb 17, 2022 at 04:48:46PM -0000, Doug Smythies wrote:
> "Welcome to the Ubuntu Server Guide! This site includes information on
> using Ubuntu Server for the latest LTS release, Ubuntu 20.04 LTS (Focal
> Fossa). For an offline version as well as versions for previous releases
> see below."

Thank you for pointing this out. This is now fixed.