Ubuntu Server documentation

Server Guide
#21

Hi Doug,
indeed it is time to adapt that - but the adaptation - for now - will be minimal.
In the most recent discussion we have considered that the main content will always be meant to apply to the latest version. Older versions are still meant to be covered and where differing they should be marked accordingly.

The reality is that maintaining them separately just is an entry to redundancy and all the issues that come with it. And on the other hand the majority of entries does not change often. For those that do it would be something like ā€œNote: in releases before XX.YY ā€¦ā€.

Example:
Former: ā€œTo achieve foo, do barā€
New: ā€œTo achieve foo, do foobar ā€¦ Note: in releases before XX.YY ā€¦ā€

That allows to document for example a feature that is added in between LTSes already when it is added. Weā€™d just state that it was not available before XX.YY. And it allows - if it changed how to do things - to outline both versions. The scale of this depends on a case by case decision. For example if on a page 95% stays the same but one aspect is different, then a little Note before a section will do. If on the other hand e.g. handling a particular workload was totally changed (e.g. we changed which program is in main to handle it) then that would more likely be an intro page linking to older/newer content.

If down the road we really have a proliferation of content due to ā€œtoo many versionsā€ we can think about splitting it, but right now that should result in the best outcome for a rather low effort.

The page already says ā€œUbuntu 20.04 LTS (Focal Fossa) and laterā€ to reflect that. Iā€™ve found that we also need to change the PDF link to say the same and I should mark the ā€œand laterā€ just as bold as the rest.

#22

You are absolutely right Doug, last update was at ā€œGenerated on 2021-03-03 03:52:43ā€.

I have to admit I do not know enough about the underlying details ā€¦ :-/
Iā€™ll get in contact with the web team who owns the machinery that converts one to the other to see what is the problem.

#23

@dsmythies - FYI I have not forgotten this, but the PDF generation is more deeply lost than anyone expected and therefore takes more time than expected to recover, but Iā€™m on it.

#24

Hi,
after PDF generation being broken for quite a while I have worked with our web team and it is now back on track - with better format and link retention than before - and finally rendered daily again.

This time the server team itself is aware where and how this is done, so I hope it wonā€™t be lost ā€œagainā€ so easily.

#25

As I said with more words before - finally PDF rendering of the server-guide content is back up and working.

#26

Hi @amichai,
for quite a while even PDF generation was broken which is now fixed.
With all the conversion now taking place in a way that the server team has actual control of I have had a look at the epub option.

AFAICS TOC works, internal and external links work, but Iā€™m not an experienced epubuser, so I canā€™t decide if the output is any good.
Could you give https://people.canonical.com/~paelzer/ubuntu-server-guide-2022-08-03.epub a try and compare it to https://people.canonical.com/~paelzer/ubuntu-server-guide-2022-08-03.pdf.

Would that be a sufficient option that youā€™d consider helpful to you and other users?

Would it need to be split in chapter files or anything else that Iā€™m not aware of?