Ingres Documentation Best Practices
A number of months ago we moved did a bit of work to take our latest documentation for the Ingres database and make it more accessible. At first we were just going to take the direct output of the documentation tool we use, but we wanted to make it dead simple to find and bookmark the docs without having to deal with frames and computer generated file names. To accomplish this feat, Andy took the XML output from the tool and threw some python at it and we’ve ended up with http://docs.ingres.com. As Ingres releases new documentation, we’ll be pushing it all out to this site for your easy access.
One of the really nice side benefits of putting out documentation out this way is the capability to use search to find just what you’re looking for. I’ll show you how to search our documentation using our own site, using google along with some tricks and tips for using google, and using our new Ingres Service Network platform currently available to our customers.
The first way to search is to use the search integrated with our web site found in the upper right corner embedded in the header. In particular, you’ll find a way to integrate this search engine right into your browser. I’ve included a short screencast to demonstrate this feature here (no audio).
While you will usually find that the search function on the Ingres web site is more then sufficient, I thought I would share with you a few tips and tricks I use with Google and the Ingres doc set.
Let’s start with a pretty typical query (at least it is when I look at our own web stats); we will search for unloaddb. Unload DB is an effective way to do a logical backup of a database or a part of a database and is sometimes used as a way to migrate from version to version or copy a database to a test or development system. Part of the issue is that you’ll find unloaddb throughout our documentation. While our search function on the website is quite good at providing you with the best scores of items, it doesn’t do the best job at pruning out results that may be of interest to the task at hand. Here’s what a typical search on google might return results like this:
With google, there are a few ways you can trim down the results of your search. In our case, the first and easiest way to start is to restrict our results to docs.ingres.com. In order to do this, you add the following to your search field:
- site:docs.ingres.com
This would now trim your results so they look something like this now:
While this is clearly very useful, we may want to find only those places in the documentation where unloaddb is the main subject of the documentation section. In order to do that, we can add the following to our search field:
- intitle:unloaddb
This restricts our results to those results that have the word “unloaddb” (case insensitive) in the title of the page. With this, you’ll see results like this:
You can see that these five results are all that are returned. Four results from the Migration Guide, and one from the DBA Guide. A nice way to narrow down the results of your search without having to dig through everything that google has to offer.