Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another knowledgeable person before making changes.
Launchpad Entry: external-links-redirects
Packages affected: ubuntu-docs
Summary
The report of bug 118741 turned into this spec: Links in documentation to external webpages should go through a redirect-page powered by Ubuntu in order to prevent link breakages.
Release Note
All external links will now be handled through Ubuntu-controlled redirect pages, which should mean a large decrease in the number of dead links in the official Ubuntu Documentation.
Rationale
Routing all external links through Ubuntu-controlled redirect-pages would make it easier for the Documentation Team to change the links in case the external URL changes.
Use Cases
- Phillipe included a link to a project's website in some documentation he wrote. However, the project rebranded after the docs were released, and changed their domain name in doing so. Unfortunately, the redirect they set up was broken; users got '404' messages when they clicked the link in the docs, couldn't get to the extra information and so reported a load of bugs. If the link had been sent through a redirecting service, Phillipe would have been able to edit the URL and fix the issue immediately.
Marvin linked to a useful howto guide in a document he wrote for Edubuntu. The domain which the document was hosted on was later bought by another company, and the document was replaced. Now, instead of getting a useful howto guide, the kids using Edubuntu get a load of pictures of ladies doing unspeakable things. Some go blind (we're talking really unspeakable things here). If the link had been sent through a redirecting service, Marvin could have simply removed the link and displayed an error message instead, which is less likely to scar the children for life.
Assumptions
- Users will not take exception to being redirected through the ubuntu.com domain
- A small script will be permitted to be added to an Ubuntu webserver by the admins
Design
A small web application should be created to handle the following tasks:
- Redirecting to another URL
- Adding a new URL which can be redirected to
- Editing an existing URL
- Displaying an error message when a redirected-to page is found to no-longer be available (can be flagged manually)
Alternative Suggestion
The author of ConnectingHelpSystems would like to suggest that the problem could also be solved by connecting the installed and online help more closely. A simple link stating "visit the online docs for a link to the current site" (linking to the wiki for the program) would do the trick. They clearly need online access to do either, so they might as well hit the most recent documentation while they are at it. A small section should be dedicated to useful external links at the top of every page, and javascript tools could help make sure all extrernal links in the document are represented at the top.
Benefits of the alternate suggestion:
- automatically provides updatability to external links using the current software
- feeds back directly to the online documentation's accuracy and currentness
- helps keep all links in sync by reducing duplicates
- still possible to add tools to report and check for links to the online help, benefiting both
- for example one tool could show all pages that use a given address to check for other places to fix
Implementation
This section should describe a plan of action (the "how") to implement the changes discussed. Could include subsections like:
User Interface
No user interface is required on the user-side. The user should be transparently redirected through the ubuntu.com domain to the relevant website. An exception is when an URL is no longer available - a standard error message should be shown instead.
Code
A small set of PHP scripts should be sufficient to implement this feature. The scripts will need access to a database table to store the URLs in.
Security
Users should be unable to change URLs themselves, although it may be useful to allow them to mark links as being dead. Only specific, trusted people should be allowed to add or make changes to URLs in the database, to prevent misuse. The table should be backed-up regularly in case it is compromised at a later date.
Migration
- Previous Ubuntu releases can't really be changed, so should just be left with non-redirected links in the documentation
- All URLs in the current ubuntu-docs SVN trunk should be added to the redirecting service, and the URLs in the documentation should be changed to corresponding redirected URLs.
Test/Demo Plan
It's important that we are able to test new features, and demonstrate them to users. Use this section to describe a short plan that anybody can follow that demonstrates the feature is working. This can then be used during CD testing, and to show off after release.
This need not be added or completed until the specification is nearing beta.
Outstanding Issues
This should highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.
- No outstanding issues at the moment
BoF agenda and discussion
Use this section to take notes during the BoF; if you keep it in the approved spec, use it for summarising what was discussed and note any options that were rejected.
- No BoF notes at the moment