One of the fundamental problems with most documentation from most technology companies is that the documentation usually contains a bunch of assumed knowledge.

Take for example, the Oracle Application Express Installation Guide for Release 4.1. This document has the following line in Section 1.4 About Choosing an HTTP server. “In order to run, Oracle Application Express must have access to Oracle Application Express Listener, Oracle HTTP Server and mod_plsql or the embedded PL/SQL gateway.” Yep. That’s right… sort of. As an experienced installer of APEX, I know that they mean: There are three different ways to connect to Oracle Application Express:

1. The Oracle Application Express Listener
2. An Oracle HTTP Server and mod_plsql
3. The embedded PL/SQL gateway

But, if I was a brand new person with no experience, I might wonder if I need the Oracle Application Express Listener + an Oracle HTTP Server + mod_plsql, or the embedded PL/SQL gateway. Reading the rest of the guide might give me an idea, but for a while I might be confused.

However, I often waffle back and forth between what the biggest problem with technology documentation is: Is it assumed knowledge? Or is it the fact that almost all technology documentation tells you what some setting or button does, but it almost always leaves out the ‘and here is why you would want to do this’ information. You could make the argument that they are one in the same, but I usually see them as different problems. The second problem really comes into play when there are choices. If there are no choices then just telling me what I have to do is fine. Just make sure I know how to do it. I once saw a step in an installation guide that was “Configure SQL/Net”. No links to other documentation. No explanation on how to do it. Just “Configure SQL/Net”. Ummm… Aren’t you kind of assuming that I know how to do that? (And lest it seem like I’m picking on Oracle here, I’ve seen this in all types of documentation from other technology companies like Microsoft and Dell to even simple things like power tools.) But when I have choices, let me know what those choices mean to me and why I’d choose one over the other.

While it would be great if all the documentation from technology vendors addressed both problems, I doubt it will happen soon. Until then we have books like Expert Oracle Application Express.

This book is 13 chapters long and each chapter was written by a different author. At first that sounds like a recipe for disaster. But when you realize that each author is a pillar of the APEX community and a subject matter expert on their chapter and (most importantly) each of the chapters is excellent, you suddenly realize you’re holding a treasure in your hands.

Each chapter contains real world experience including the all important ‘and here is why you would want to do this’. If fact chapter 1 by John Scott addresses the above connection to Oracle Application Express issue. Sure there are three ways to do it, but why would I want to use one way or the other? Well, read chapter 1 and you will know.

I spent 14 years at Oracle and taught hundreds of people how to use Oracle Application Express and I thought at least some of the chapters would be a bit of a review for me, but I can truly say that I learned valuable information from each and every chapter.

I highly recommend this book to anyone who is going to be using Oracle Application Express.