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.

Searching IBM Cloud documentation with logical operator for “code engine” AND serverless.

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:

Navigate the IBM Cloud documentation by section.

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:

Use filters to scope your search.

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:

Searching IBM Cloud docs using an Internet search engine.

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

More from Cloud

Hybrid cloud examples, applications and use cases

7 min read - To keep pace with the dynamic environment of digitally-driven business, organizations continue to embrace hybrid cloud, which combines and unifies public cloud, private cloud and on-premises infrastructure, while providing orchestration, management and application portability across all three. According to the IBM Transformation Index: State of Cloud, a 2022 survey commissioned by IBM and conducted by an independent research firm, more than 77% of business and IT professionals say they have adopted a hybrid cloud approach. By creating an agile, flexible and…

Tokens and login sessions in IBM Cloud

9 min read - IBM Cloud authentication and authorization relies on the industry-standard protocol OAuth 2.0. You can read more about OAuth 2.0 in RFC 6749—The OAuth 2.0 Authorization Framework. Like most adopters of OAuth 2.0, IBM has also extended some of OAuth 2.0 functionality to meet the requirements of IBM Cloud and its customers. Access and refresh tokens As specified in RFC 6749, applications are getting an access token to represent the identity that has been authenticated and its permissions. Additionally, in IBM…

How to move from IBM Cloud Functions to IBM Code Engine

5 min read - When migrating off IBM Cloud Functions, IBM Cloud Code Engine is one of the possible deployment targets. Code Engine offers apps, jobs and (recently function) that you can (or need) to pick from. In this post, we provide some discussion points and share tips and tricks on how to work with Code Engine functions. IBM Cloud Code Engine is a fully managed, serverless platform to (not only) run your containerized workloads. It has evolved a lot since March 2021, when…

Sensors, signals and synergy: Enhancing Downer’s data exploration with IBM

3 min read - In the realm of urban transportation, precision is pivotal. Downer, a leading provider of integrated services in Australia and New Zealand, considers itself a guardian of the elaborate transportation matrix, and it continually seeks to enhance its operational efficiency. With over 200 trains and a multitude of sensors, Downer has accumulated a vast amount of data. While Downer regularly uncovers actionable insights from their data, their partnership with IBM® Client Engineering aimed to explore the additional potential of this vast dataset,…

IBM Newsletters

Get our newsletters and topic updates that deliver the latest thought leadership and insights on emerging trends.
Subscribe now More newsletters