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 -- ubuntu-server mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/ubuntu-server More info: https://wiki.ubuntu.com/ServerTeam
