My best practices for working with product documentation.

I often answer technical product questions on all kinds of IBM Cloud topics and Db2-related problems. To provide relevant links and to back up my “hunch” after reading a question, I typically search the relevant documentation. But what are efficient ways to search in the IBM Cloud documentation? What are good ways to find the relevant parts in the Db2 documentation? Here are my best practices on searching documentation.

Overview

Before I start with the actual search, let’s begin with some basics. Most documentation is organized and structured into categories or parts. Typically, the product documentation itself provides a search form — in many cases with some filtering options. And most documentation is missing an introduction on how to use the documentation and its search. The good news is that most search engines — either built into the documentation portal or regular Internet search portals — offer some basic logical operators and common search capabilities.

First navigate, then read

This first approach is a quick way to find the relevant parts when you know where to locate it. Let’s take a look at the IBM Cloud documentation portal:

Below the search form are tabs for sections like Develop, Tutorials or API & SDK reference. If I wanted to find something in the docs for IBM watsonx Assistant, I would click on All product docs, then check the box for the category AI/machine learning and then locate the tile for watsonx Assistant (managed). Similarly, I could enable the category Databases to only see tiles for, e.g., Db2 on Cloud or Databases for MongoDB. 

Within the service documentation, typically there are sections named Get Started, Tutorials, How to, Reference and more that organize the offered information and make it easier to find the relevant page or subsection. For watsonx Assistant, the page Expressions for accessing objects is under Reference. I use that page quite often for help on how to process chatbot input.

You can use the same approach of filtering on categories first when using the documentation tabs (see screenshot above) for Tutorials, API & SDK reference or FAQs (frequently asked questions).

The bottom line is that this strategy of first navigating and then reading works well when you are experienced in “RTFM” or want to just explore the documentation section by section.

Built-in search

Generally, when searching for something, it is best practice to enter the correct search term. At the time of this writing, there are nine documents returned when you search for “python runtime” (with quotes), but over 750 pages for a search for python runtime. Thus, use quotes to group single words to a search term depending on what you want to search.

I also use the logical operator AND. It requires that both terms need to be in the found result, but not next to each other. Searching for python AND runtime returns about 80 documents. Compare that to the numbers from above.

Another helpful technique is to use filters. When you are in the set of pages for a single service and use the search field on the upper-right side, the search is scoped to that service. The search field for the IBM Cloud docs offers a filter by clicking on the icon shown next to the x (see below). It opens an overlay dialog to scope the search to  a selection of categories or individual sections:

When working with the built-in search, I often combine the use of quotes around multiple words, the ANDing of search terms with scoping the search to specific services or a group of them.

Internet search engines

An alternative to the built-in search are utilizing Internet search engines like Bing, DuckDuckGo, Ecosia, Google, Startpage, Qwant or others. Type in your search term including the keyphrase “IBM Cloud” (with quotes!) and press the search button. It often leads to good results.

But did you know that you could optimize it by telling most search engines what/where to search? Often, you can scope your Internet search to specific domains and subsets of pages. Use the term site:cloud.ibm.com/docs as part of your search and it will only consider pages from the IBM Cloud documentation. Compare the results from DuckDuckGo below for site:cloud.ibm.com/docs “code engine” serverless with those using the IBM Cloud documentation search for “code engine” AND serverless in the top screenshot:

Each search engine has its own style and set of features to use. Check out the, e.g., DuckDuckGo search syntax or Startpage page on search operators. The search phrase site:cloud.ibm.com/docs “code engine” intitle:CLI looks for IBM Cloud documentation for Code Engine with the word CLI in the page title.

Conclusions

There is no single way of how to consume or search documentation. It depends (!) on what you are searching for, your experience with the specific documentation and with search engines. Thus, try out the discussed options and pick what fits you best, both in terms of results and convenience. The shown techniques work for IBM Db2 documentation, too. Only the URLs are different.

If you have feedback, suggestions, or questions about this post, please reach out to me on Twitter (@data_henrik) or LinkedIn.