Oracle Documentation URLs : What I would like to see!

Broken-LinkAfter my recent rant about broken URLs, I thought it would be sensible to say something a little more constructive, so this is what I would do if I were asked to structure the documentation. Other opinions are valid. ūüôā

Base URL: I’m assuming the base URL for the database documentation¬†will never change again from it’s current value.

Version: Next comes a version. Personally I would have a separate version for every patchset, so you can easily flick between them to see the variations in the documentation, but I would also have a concept of the “latest” for each major release and the “overall latest” version of the page, so you can always link to the most up to date version of the document if you want. That means, whatever happens with new releases, you will always have the link pointing to the latest page for that feature, unless of course the feature has been removed. All previous version of the docs will remain and the URLs will still be valid. Believe it or not, sometimes people really do need to read the old¬†documentation!

Book: Some indicator of the book the page belongs to. Oracle are already doing this with things like “DBSEG” for Database Security Guide. This must¬†never change!

Page: A slug representing the page. It would be nice if these were human readable, like “audit_admin”, but if they want to use those crappy GUIDs, that’s fine, provided that they are¬†cast in stone as the ID for that page, regardless of version forever. The GUID must not be unique for¬†each version of the page, or it makes it impossible to easily switch between the same page for different database versions.

Internal anchors: Some of the internal anchors in pages have some odd behaviour now. You click a link, which takes you to the correct part of the page, but the URL bar still shows the top-level page URL. As a result, if you grab the URL for a link in your blog, you are not really pointing to the correct place on the page. So you have to find the original link you clicked and copy that, so you are really getting to the link you want. Very annoying! Internal anchors should be consistent, visible and live forever. If you want to change the anchor, you can add a new one in addition to the old one. Nothing wrong with that! Once again, the ugly GUIDs are acceptable here, but only if the GUID for an anchor never changes, so to read the same section of text in another DB version, you only have to change the version part of the URL.

As an example of all this, let’s think about the “Administering the Audit Trail” page from the 12c documentation and show how this could be handled going forward.

  • “/12.1.0.1/DBSEG/audit_admin.htm”
  • “/12.1.0.2/DBSEG/audit_admin.htm”
  • “/12.1-latest/DBSEG/audit_admin.htm” :¬†Points to 12.1.0.2 unless¬†a newer patchset is released for the 12.1 release.
  • “/12.2.0.1/DBSEG/audit_admin.htm”
  • “/12.2-latest/DBSEG/audit_admin.htm”¬†:¬†Points to 12.2.0.1 until a newer patchset is released for the 12.2 release.
  • “/latest/DBSEG/audit_admin.htm” :¬†Points to the very latest version of the page. The latest patchset for the latest release (12.2.0.1, 13.1.0.1 etc.).

This would allow all versions of the docs to coexist. You could switch between them easily, as in most cases, the only thing to you ever need to change is the version number. A perfect example of this can be seen in the MySQL documentation, which is organised beautifully. It’s so simple the pages include version links so you can switch between version with a single click.

I appreciate there are situations where things would not run to plan, like when features are removed, or expanded to the point where pages are split into several new pages etc. These could still be catered for if a sensible approach were taken, like the original page becoming a “link page” to all the expanded content.

I would not expect Oracle to retro-fit all the old documentation, as that would be a massive task and break even more links, but something more sensible and future-proof needs to happen compared to what we have seen in recent years, which to be brutally frank has been a clusterfuck on a monumental scale!

I know Oracle are taking steps to address this issue. I just hope their solution is not more smoke and mirrors and actually starts to resemble a basic filing system!

Cheers

Tim…

Any DBAs out there thinking of Optimal Flexible Architecture (OFA)? ūüôā

Update: Apart from being ugly, I have no real problem with the GUID. My only worry is Oracle will assign a new GUID for a page for each version (typo correction, release, DB version etc.) of the same page, thus making the whole switching between DB versions by altering one part of the URL impossible. If they do this constant change of the GUIDs, it will also result on one of two things.

  1. If the old version of the page is not kept forever, you will have yet more broken links.
  2. If pages are¬†kept forever, that’s better, but if a new GUID is created for every small revision of the same page (within a database release/version), you will continue to point to the old uncorrected page, which will lower the quality of your links.

So the GUIDs themselves aren’t the problem. It’s how they “could” be used that “could” be the problem. Think about the possible scenarios during the lifespan of a single section of the documentation and I think you will see how disastrous this could be.

 

Writing Tips : A URL is for life, not just for Christmas!

writingI’m currently doing yet another pass through my¬†whole website correcting broken external links. This is nothing to do with my bad management. This is to do with people changing their URLs and not putting the correct redirects in place. I’ve just done a scan of my website and there are over 800 broken links to Oracle documentation!

There seem to be several ways people deal with URL changes on their website.

  • They do nothing and quite happily let broken¬†links fail and get picked up by their 404 error page.
  • They put in a¬†generic redirect page that takes you to the top of the website, not the original content the link pointed to.
  • They put in a correct redirect, but only for a limited period, after which, the URL¬†fails and you get the 404 page.
  • They put in place a proper redirect and it stays there forever, so all previous URLs for the content continue to work and direct to the correct content.

In my opinion, the only acceptable option is the last one. A URL is for life, not just for Christmas. A variant of this slogan from my childhood. ūüôā

From your perspective, broken links (internal and external) are bad for your website. It’s annoying for your readers and make your site appear poorly maintained. Broken links are one of the factors search engines use to judge your website, so it is in your interest to keep things ship-shape.

Being an Oracle blogger can prove difficult at times as Oracle have this annoying habit of changing their URLs a lot and not putting the correct redirects in place.

Don’t add to this problem. Once you start writing, try to keep all the URLs alive forever. If you move your blog to a different service, leave the old one there and put links to the new location. If you self-host, life is easier as you can do redirects using “.htaccess” or directly in your “httpd.conf” file.

You can identify broken links in your site using a link scanner. I’m currently using SiteCrawl.net, which seems to do the job OK. Once you’ve identified the broken links, you can start the arduous task of correcting them. This involves finding the new home of the content and correcting your link¬†to it. It’s not fun, but it has to be done. Once you see how boring and annoying it is, you will appreciate how important it is that you don’t piss off other people by not maintaining your own URLs.

Cheers

Tim…