Over the years I’ve written a lot about the state of the Oracle documentation. This post is based on some Tweets by Bruno Borges related to the Java documentation, which I totally agree with.
Let’s start by saying, we’ve come a long way! Back when I wrote this post in 2015 we were in a really bad place. If you look at things now *for the database*, it is a lot more similar to what I was suggesting back then, at least as far as the new documentation is concerned. For example with this manual, all you have to do is alter the version number to switch between versions. Sensible!
- https://docs.oracle.com/en/database/oracle/oracle-database/12.2/admin/index.html
- https://docs.oracle.com/en/database/oracle/oracle-database/18/admin/index.html
- https://docs.oracle.com/en/database/oracle/oracle-database/19/admin/index.html
What Next?
What I would like to see is this URL also, which always takes you to the latest version of the manual!
- https://docs.oracle.com/en/database/oracle/oracle-database/latest/admin/index.html
What’s more, the canonical tag on all documentation should point to the latest link. In the case of this page, on all versions we would have this.
<link rel=”canonical” href=”https://docs.oracle.com/en/database/oracle/oracle-database/latest/admin/index.html” />
Why? We have a problem when searching for stuff. For example, Google for “DBMS_APPLICATION_INFO” and you get the 10g page. You have to actively Google for “DBMS_APPLICATION_INFO 18c” to get the correct page. Using the canonical tag is one way of solving that.
What about old versions?
They are still a mess. I’m not sure it’s worth the effort of fixing them, other than maybe canonical tags.
What about the content?
Every version of the database documentation gets better. There are still mistakes and “example code” that couldn’t possibly run, but it is a lot better than the old days. The introduction of the “2 Day …” manuals has improved things for beginners, but there still needs to be some work. Things I would like to see include.
- Proper staged content, from beginner to deep dive. Much of the documentation is still very reference focused. New people don’t stand a chance.
- Working examples. I would prefer if these were in the docs, rather than a link out to other things.
- More manageable page sizes. Most pages are massive, and quite daunting.
- Embedded videos where appropriate.
- Most importantly, all content needs to be centralised.
Much of this content exists, but it’s spread across different resources, which makes is really hard for people to navigate.
What about other products?
This is where is all gets dodgy. Some of the other products aren’t as consistent as the new database stuff. Bruno was talking specifically about Java, and it is a bit of a mess. There are some good resources, but they are scattered and of varying quality and age. There is an entry point from https://docs.oracle.com/en/, but a few clicks down and you soon jump across to completely different sites. I hope the intention is to gradually bring all of this under the central location, with the appropriate redirects to make sure everyone finds the central location.
Is there an example of this?
Yes. I was discussing Bruno’s comments with a colleague and he pointed out what Microsoft are doing here. You can read about the project here.
I hope Oracle have similar plans for their documentation site. The popularity of other sites, including my own, suggest there is still some work to do before the documentation is consumable by normal people. 🙂
Cheers
Tim…
