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.

 

Author: Tim...

DBA, Developer, Author, Trainer.

19 thoughts on “Oracle Documentation URLs : What I would like to see!”

  1. AND, unless someone foolishly plays with the links you should be able to access the date last modified for the document page from the properties of the link. Both in the general documentation and especially in update/upgrade guides being able to find all the pages that have changed since some past date would become tractable (perhaps even easy).

  2. stee1rat: I wanted something that was mobile friendly, so I reverted to the standard theme. Not sure how long I will stay with it, but I’ve not found anything I like better yet… 🙂

  3. Give ’em another kick for me, please. I’ve been having more and more people reporting broken links to the Oracle docs from my website as well. I’d create a blog entry about it, but you’ve said it all. Besides — you have bigger boots to do the kicking with.

  4. Mark: My link checker revealed that you included a broken link in the comments about an article on broken links. You are a fiend. 🙂

    Cheers

    Tim…

Comments are closed.