Fixing broken links to Oracle documentation… Again…

Broken-LinkWith my recent website move I thought I better check for broken links, in case I had screwed anything up during the transfer. The last few times I’ve done this I’ve used SiteCrawl, which seems to do a decent job.

After the scan had finished I looked through the results and had a couple of broken internal links and 171 broken external links. Can you guess where the vast majority of the broken external links were pointing to? Yes, it was Oracle documentation. A quick search on my blog reveals about six rants I’ve posted about this over the years. There have been many more incidents of course.

Fixing this stuff is very time consuming and boring. What’s worse, it robs me of time I could spend on creating new content.

I’m guessing most content producers don’t go back and check for broken links. Oracle certainly don’t because I see them all the time in whitepapers, articles and forum entries. The result of this is a sea of helpful content produced by the community that are littered with broken links to Oracle content. It lowers the value of the community content, through no fault of the content producer.

Oracle. Please stop doing this! You are constantly devaluing the content produced by us in the community!

Cheers

Tim…

Update: You should probably read this by Kim Berg Hansen.

Feedback from the Oracle documentation team

feedbackI got some feedback from the Oracle documentation team, based on my recent post.

GUIDs

One of the concerns I raised was about how the GUIDs would be used in different releases of the documentation. Although I don’t like the look of the GUIDs, I can understand why they might be more convenient that trying to think of a neat, descriptive, human readable slug. My concern was the GUID might be unique for every incarnation of the same page. That is, a new GUID for the same page for each patchset, DB version and/or minor text correction. That would make it really hard to flick between versions, as you couldn’t predict what the page was called in each variant.

It seems my worries were unfounded. The intention is the GUID of a specific page will stay the same, regardless of patchset, DB version or document correction. That’s great news!

Broken Links

The team are trying to put some stuff in place to correct the broken links. I think I might know who is developing this solution. 🙂

The quick fix will be to direct previously broken links to the table of contents page of the appropriate manual. Later, they will attempt to provide topic-to-topic links. No promises here, but it sounds promising.

Conclusion

I’m going to continue to fix the broken links on my site as I want to maintain the direct topic links in the short term, but this sounds like really good news going forward.

It also sounds like the documentation team are feeling our pain and putting stuff in place to prevent this happening in future, which is fantastic news! 🙂

Note to self: It’s much better to engage with the right people and discuss the issue, rather than just bitch about stuff.

Cheers

Tim…

Oracle : Do you even internet? (broken links again)

Broken-LinkI mentioned in a recent post that Oracle are often guilty of changing URLs, which breaks all the documentation links in your site. Someone replied with this link. I knew I had a lot of clean-up to do, but I expected most of it to be old URLs, like stuff pointing to 8i, 9i etc.

I’ve just been looking and vast swathes of links have been changed in the 12.1 docs. In some cases, articles I wrote a couple of weeks ago are screwed. The reference manual is guilty of this big time!

  • Before: http://docs.oracle.com/database/121/REFRN/refrn10140.htm
  • After: http://docs.oracle.com/database/121/REFRN/GUID-70035A22-E031-4975-A51C-871AE1F2F260.htm#REFRN23823

Check this one out too.

  • Before: http://docs.oracle.com/database/121/SUTIL/release_changes.htm#BABEJJAA
  • After: http://docs.oracle.com/database/121/SUTIL/GUID-F4EE2A42-3986-4597-9088-A506173ABABF.htm#GUID-0FC02CF3-D149-4EA9-AE3E-CB869921CF40__BABEJJAA

I’m not even going to make them links, because they will probably change again next week. 🙁

URLs DO NOT CHANGE!

This is really basic internet stuff. If you must change them, you have to put proper redirects in place so people can still get to your content FOREVER!

I’ve written about Oracle doing this before (here and here).

I’m always trying to encourage people to get involved in the community, but how can they possibly write good content if it is riddled with broken links to the docs? Going back to repair old content is soul destroying, so don’t make them do it!

Oracle. Please, please, please learn how to internet!

Cheers

Tim…

PS. Check out the MySQL documentation. It is arranged so neatly and you can flick between versions so simply. I know the documentation is much smaller, but something like this must be possible with some planning!

Update: I’ve written something a little more constructive on this subject here.

Broken(ish) Links…

A couple of days ago Sten Vesterli tweeted about the URL changes on OTN. The previous base URL of “http://www.oracle.com/technology” has been replaced by “http://www.oracle.com/technetwork“. There are redirects in place, so for many of the top level pages this isn’t a problem, but some of the deeper links result in “page not found” errors or redirect to rather generic pages.

Fortunately, most of the links from my site are to the Oracle docs, whose URLs haven’t changed, but there are also plenty of OTN links. I’m trying to clean up the problem links, but it’s going to take a little time. If you spot any broken links, or links that don’t look like they point to the intended information, feel free to contact me and I’ll do my best to sort them.

Cheers

Tim…