Why Automation Matters : Your automation is your documentation

How many times have you been following a process defined in a knowledge base note, only to find something has been omitted, or is unclear? This may be because of empire building, laziness or more often oversight, but the result is the same. Unless your processes are well documented, you always run the risk of progress drawing to a halt when “the right person” is not present.

One of the great things about automation is, by definition, every step of the process must be defined. If person X is on holiday, you can be 100% sure all the steps to complete the automation are present.

Of course, this doesn’t stop people writing stupid, ugly and hard to understand code, but your development process should have some control over that. Even if it doesn’t, you know the answer is there. It must be there because the process works.

Does that mean you don’t need to document automations?

No. The automations should be self documenting. I don’t mean that in the sense that “my code is so good it’s self-documenting”, which is the calling card of the lazy developer. I mean that automation code in your source control system should be documented. Markdown is a quick and easy tool that allows us to easily document our code, and the good thing about it is it remains close to the code. It’s right next to it in the repository. When we change our code, we should revise our documentation where necessary. The documentation becomes a living document, rather than some 1000 page word document that nobody ever reads, and nobody updates.

But documentation sucks!

Documentation gets a really bad rap because most people are doing it wrong. They fall into one of these traps.

  • They produce too little, which means people are unlikely to find what they are looking for.
  • They produce too much, which makes it daunting to look at, so nobody bothers.
  • It’s overly formal, which is dry and boring.
  • It’s hidden, or at least separate to the code, so people might not even know it exists.

Basic pointers and how-to examples are good enough for 90% of the cases, so make these the focus of your documentation. You can always give links to more detailed documentation for those people that need a little more. The context is slightly different, but this post on Structuring Content should give you some clues about how to structure your documentation. After all, documentation is content. šŸ™‚

Conclusion

For some companies an automation or infrastructure as code project may well be the first time in their company history that they have got everything about a process documented. That has to be a positive result for the company!

Check out the rest of the series here.

Cheers

Timā€¦

Oracle Help Center of the Future: Reimagining Documentation (COLLABORATE 19)

If you follow me on Twitter you will know I recently had a conference call with the Oracle Documentation folks. We were discussing a number of points, some of which were related to a blog post of mine here.

Following that Roland Mcleod from the team mentioned they would be at Collaborate 19. This is an ideal opportunity for people to give their feedback directly to the team, and help shape the future of the documentation. Please go and speak to them, and give some constructive feedback about the documentation for whatever Oracle products you work with. Let them know what you like, dislike and how things would work better for you! It’s important they understand how you like to consume information, if you want the documentation to improve.

It’s also important that a variety of people get involved. Young, old, experienced and fresh to the game. We all like to consume information in a different way, and it’s important the documentation works for everybody.

I also said I would give their Collaborate 19 sessions a shout out, so here is what Roland sent me.

Can you reimagine Oracle Documentation and Help?

The Oracle Help Center is undergoing a complete redesign. We need all customers, partners and consultants to help us make it work for you.

Please attend one of our sessions and come by to see us at the Oracle Exhibit Area: Oracle Help Center Ambassadors!

Session ID: 112040
Oracle Help Center of the Future: Reimagining Documentation
10:30 AMā€“11:30 AM Apr 8, 2019
CC 2ND FL 225B

Oracle Help Center of the Future: Reimagining Documentation
3:15 PMā€“4:15 PM Apr 8, 2019
CC 2ND FL 225B

Session Abstract: In this interactive session; you’ll have an opportunity to provide your feedback about the current and future Oracle Help Center (docs.oracle.com). You will be invited to share how you use documentation in your role and at your organization. This session includes a brief preview of the future Oracle Help Center experience.

Cheers

Tim…

Oracle Documentation : It’s getting better, but…

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!

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…

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.

 

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…