The Evolution of the Oracle Documentation
This post was originally published on this site
When was the last time you looked into the Oracle documentation? If you rarely or never do so because you think you know the Oracle database, take another look at docs.oracle.com and browse in the online documentation. It’s worth it!
A few weeks ago, I was asked in a comment on my blog post Bitmap-based COUNT(DISTINCT) Functions in Oracle 19c whether this feature requires additional licensing. Where can we find such information? In the Oracle documentation, of course! But where? The Database Licensing Information User Manual would be the right place for such information, and if you don’t find the feature there, it is probably included in all database editions. I admit, a not very promising approach, but for a long time, it was the only feasible way.
Since Oracle 19c, there is a much more comfortable way to find such information: The Database Features and Licensing App.
Screenshot of Database Features and Licensing App
In this APEX application, you can search for individual features and keywords and find in what database versions they are available and are the license requirements. The search can be filtered on specific focus areas or database versions. A really helpful tool and much easier to use than the old-fashened (but of course more detailed) licensing manual. This is just one example of how the Oracle documentation was improved over the years.
Back in the Old Days
If you work with Oracle for a long time, you perhaps still remember these printed Oracle manuals with a white cover that could be ordered as paper-back books. In the first company I worked with Oracle databases, we had a book shelf full of manuals for Oracle7. Unfortunately, I no longer have any of these books nowadays, it would have been nice to take a picture of them for this blog post. But if you are interested to read about Oracle database version 7, you still can find the complete Oracle7 Server 7.3.4 Documentation Library online.
Dear reader: If you still have some of these old books at home or in the office and could send me a picture of them, I will include it in this blog post (of course with mentioning the photographer). Thanks!
With every database version, the number of books increased, and each book got more and more pages. When we started to use version 8, the number of books increased so much that my former boss asked: “Do we really need all these books? Can you tell me which manuals you need regularly?” So, he ordered just the most important books (about one meter of paper in the shelf), and the complete documentation on CD-ROM.
Oracle Help Center
Most of us will not miss the printed books, but are happy that the entire documentation is available online for free. For Oracle customers that seems to be obvious, but there are many other software vendors that do not provide free online documentation (or no documentation at all). In the Oracle Help Center, you can find the documentation for all Oracle products – much more than all of us will ever read. The URL is easy to remember: docs.oracle.com
Because there are many Oracle products I never use, and I mainly need the database documentation, I normally use a direct bookmark to the Oracle Database Documentation. It contains all books in HTML and PDF format for the current database versions, but also for earlier releases back to Oracle 7.3. The structure of the documentation library changed over the years, but many of the books are still the same – except for the updated and extended content, of course. For example, the SQL Language Reference (one of the thickest books, as I remember) of Oracle 7.3 contains 741 pages in the PDF version, 37 pages only to explain the syntax of the SELECT statement. In Oracle 19c, the same PDF book contains 2263 pages, 95 of them for the SELECT. Not all books grew so much, but because of all the new features that were introduced in all the releases of the Oracle Database, the documentation increases with every release.
Structure of Oracle Documentation Library in versions 8.1.7 and 19c
The quality of the documentation varies depending on the book. Some of the books are very well structured and informative to read. One of my favourites is the Data Warehouseing Guide – not only because I mainly work in this area. It contains a lot of useful information about Data Warehouse design, Materialized Views including Query Rewrite, many ETL features, analytical queries and Analytic Views. When I prepared a presentation about Query Rewrite last year, I realised once again how much detail information can be found in this book. That’s why one of the design tips at the end of the presentation is: Read the Oracle documentation (or a bit more unpolite: RTFM).
At the other end of the quality scale was a book that is no longer relevant today: The Oracle Warehouse Builder OMB*Plus Command Reference. The scripting language of OWB was very powerful, but a book with more than 500 pages of EBNF syntax definitions without any meaningful explanations is hard to read and even harder to understand. Whenever I used OMB*Plus, the approach with “try and error” was faster than to look into the manual.
Documentation Becomes Interactive
Additionally to the “traditional” documentation in HTML and PDF format, Oracle started with interactive ways of explaining the concepts and features of the Oracle database. Since Oracle 12c, more formats are integrated in the Help Center. The Database Features and Licensing App I already mentioned at the beginning of this post. Online tutorials, embedded videos or links to Oracle Live SQL are available in addition to the written manuals.
Especially Oracle Live SQL I find very useful to learn about new features, either using existing tutorials or running your own SQL statements or scripts in a browser-based SQL Worksheet. Many scripts and tutorials about all kind of SQL related topics are available on this platform. You can run them in any browser. For example, if you find yourself on a desert island (with internet access) and don’t have an Oracle database within reach, but you want to know immediately how SQL Pattern Matching works, you can try it on your mobile phone with Oracle Live SQL. Of course, you also can run the tutorials and scripts on your computer in your office or at home – presumably a more realistic use case. You can also write and store your own scripts on the plattform and share them with other people.
Oracle Live SQL contains many tutorials and scripts in its code library
You want to know what background processes are part of a database instance or what memory areas belong to the SGA (System Global Area) or the PGA (Private Global Area)? All this information about the technical architecture of the Oracle database can be found in the Database Concepts manual since years, which is of course updated with every database version. Alternatively, you can also use a more interactive way to get an overview of the architecture: The Interactive Architecture Diagrams are available since version 18c (in 19c also for the RAC architecture).
Overview page of the Oracle Database 19c Interactive Architecture Diagrams
Not only the Oracle database gets a lot of new features with every version, also the documentation is improved over the years. Compared to many other software vendors, Oracle has a very detailed and high quality documentation library. Sometimes it’s not easy to find the right place in the manuals immediately, but once you are familiar with your favourite books and interactive apps, the Oracle Help Center is a very useful source for information about the Oracle database.