Ubuntu Server Guide: call for content and reviews

[Bryce Harrington]

On Thu, Sep 12, 2019 at 05:44:15PM -0700, Doug Smythies wrote:
> On 2019.09.12 13:26 Joshua Powers wrote:
> There are a great many dead links, and I don't know how many links
> that should not be links. For example [4], see index.pl as a link and
> ??? as a non functioning link, but should go to [5].

This is true, the links need some maintenance work.  I'm spotting
several classes of breakage, two of which you've mentioned:

 * Internal cross-linking.  I think the link you mention in [4] is this
   type.  The old documentation links to the Backup page,
   (https://help.ubuntu.com/lts/serverguide/preparing-to-install.html#backing-up) 
   but I suppose the conversion process couldn't recalculate the link
   and left "???" as a placeholder?  Referring to the original doc
   should help identify where these should be pointed in the updated
   doc.

 * Macro reference links.  Guessing the wiki had some shortcuts, such as
   "[Ubuntu Web site](&ubuntu-web;)", that are resulting in empty links
   such as the one you point out on the Apache2 page.  I'm not sure
   discourse has such functionality, so may be more maintainable to
   simply replace these macros with direct links.

 * Outdated links.  Some links go to existing documentation, but for
   versions of software older than what we carry.  This doesn't seem to
   be an issue for the Apache2 page (it links to Apache 2.4 docs,
   and eoan has 2.4.41).  Obviously updating these is an important part
   of the maintenance work for this doc as it moves from one LTS to
   another.

 * Example links.  "www.ubunturocks.com" is used in this documentation
   as an example for configuring apache.  It doesn't look like this is
   intended to be displayed as a clickable link, however Discourse seems
   to be automatically linkifying it.  The ubunturocks.com website seems
   no longer online though, so the result is what appears to be a broken
   link.  If the link is turned into a pre-formatted link
   (i.e. `www.ubunturocks.com`) it should display better.  I also
   suspect using a more obviously generic url (e.g. `www.mynewsite.com`
   in this case) would be less likely to confuse readers in the future
   as websites come and go.

 * Book links.  The References section includes a link to O'Reilly's
   Apache Cookbook, however this points at the 1st edition rather than
   the current 3rd edition.  I suspect in nearly all cases we should be
   pointing at current editions of print materials, so book links even
   if they resolve correctly, should be doublechecked for currentness.

 * Dead external links.  I've spotted one or two cases of standard
   linkrot on a few pages, such as to now-missing blog posts or ezine
   articles.  I suspect for ease of maintenance in the future it may be
   best practice to avoid such links when possible, perhaps directly
   including that information into this guide.

While changing links over, may also be worth swapping in https links
instead of http ones, but only where it's feasible.  The Mod SSL docs
link, ironically enough, seems to have http but not https, however the
apache.org links all redirect to https so we may as use https in these
cases.

For the Apache2 page, I've gone ahead and fixed up all the items
mentioned above, but the above link maintenance process should be done
on each of the pages in the guide, and re-done every LTS.

Bryce