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 are 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.

 

Oracle Documentation: The broken links fiasco continues…

So I was just patting myself on the back for finishing my website clean up, then I happened on a few pages with broken links to Oracle documentation. That annoyed me, but I figured I better do a quick scan to see how many broken external links I had. The first attempt was a complete fail because the tool I used clicked all my Google Adsense adverts, making me a DotCom millionaire in about 3 minutes. I wrote to Google and apologised profusely. In my defense, the tool I used was right at the top of the list in the Chrome Web App Store…

Once I got a link checker that didn’t put me at risk of a jail sentence, things got a little more depressing. A very large number of my articles contain broken links to Oracle documentation. As I started looking at links it became apparent that Oracle have used at least 3 main URLs for documentation over the years:

  • http://download-west.oracle.com/docs (8i -> 10gR2)
  • http://download.oracle.com/docs (11gR1 -> 11gR2)
  • http://docs.oracle.com/ (post 11gR2 stuff)

The versions listed are based on the links I’ve added in my articles. If you check today, all/most docs come from the “http://docs.oracle.com” address.

This in itself shouldn’t present a problem, because any company with an involvement in the web knows that URLs should never change. If by chance you do have to change something, you put a redirect in place. The problem is, Oracle don’t do this, or at least not consistently. Check out the following three URLs:

They are the same document, just using the three base URLs I mentioned previously. If you click them, you’ll notice the first one fails and the following two work. My guess is Oracle have created a 301 permanent redirect from “http://download.oracle.com/docs” to “http://docs.oracle.com”, but not bothered to maintain the “http://download-west.oracle.com/docs” URL, thereby breaking just about every link to its docs on the internet that references anything older than about 11gR1. That includes forums (including their own), blog posts, documents containing URLs etc. It’s just a nightmare.

So PLEASE Oracle:

  • Stop changing URLs.
  • When you do change them, PLEASE use rewrites/redirects properly.
  • Remember, your rewrites/redirects should be permanent, not just long enough for search engines to update their indexes.

This would solve the vast majority of my gripes about the links to the Oracle docs…

Notes:

  • For those not familiar with web servers, this kind of rewrite/redirect for a whole domain name is really simple. It’s one line in your “.htaccess” file, not a separate one for each page, so I’m not asking for the world here. :)
  • I am aware there are other issues with changing URLs at Oracle that a blanket redirect would not solve. I’m not even going to start on whitepapers and PDFs…

Cheers

Tim…

Let me search the Oracle documentation for you!

You sometimes get questions that are easily answered by a Google search, so you give people a link to lmgtfy.com, like this.

http://lmgtfy.com/?q=Oracle+11gR2

As a homage to lmgtfy.com I’ve created a documentation search.

https://oracle-base.com/search/

If you specify your search it gives you a URL you can pass to others. When they use the URL it shows them what they could have done rather than bug you. :)

https://oracle-base.com/search/?txt=automatic+storage+manager

Update: It now uses TinyURL, like this http://tinyurl.com/yamsmc2

It’s a little basic to look at, but it made me laugh. :)

Cheers

Tim…