Contemporary Prompt

The documentation system tenet of contemporary prompt states that documentation should be queryable using a contemporary prompt interface. A contemporary prompt interface combines recommendations, checkspelling, search, question and answers, and previews, all within a closed-loop user experience. This tenet supports the principle of low cognitive load, by reducing the time and motions that stand between a knowledge gap and the provision of relevant content.

The traditional search box is no longer used just for search nor search is confined to a box. What users expect today is a more general capability, a prompt, which works as a universal mechanism for all human to machine communication use cases. Yes, we can still use the prompt to search, but we normally use it to ask questions, throw random words, find out what other people typically are interested in, check our spelling, translate words, and so much more.

Given that “information is not only a source of power, but a source of confusion” (Wilensky,  1967, as cited in Choo, 2002), prompts are today the most effective mechanisms to find the proverbial needle in the haystack. 

Prompts are so pervasive and essential in modern human computer interaction (HCI) that they are either one click, one swipe gesture, or one keystroke away in most modern compute devices. On Apple iOS devices for example, the prompt is displayed by simply swiping vertically from the top. Enterprises could provide a world class enterprise documentation experience to their employees by integrating their search indexes and large language model (LLM) services directly into native operating system built-in search prompts, such as MacOS Spotlight or Windows search.

Let us now look at some of the most salient prompt capabilities:

Default recommendations

Prompts have memory and context. What you have typed before, in which context you typed it. If you have used the prompt before, it should be in a good position to predict what you are likely to want next, depending on the time of the day, your geographic location, and so on. Just hovering or bringing the prompt into focus should be sufficient to display such default recommendations.

Contextual autocompletion

Most complex terms should be automatically identified using one or two keystrokes. In other words, the workflow for most users should be as simple as bringing the prompt into focus and pressing one or two keys—say, ‘c’ and ‘u’ to match ‘Customer’—for the autocompletion algorithm to provide an adequate complete search term which then uniquely identifies the desired answer or information snippet. To achieve such an experience, the auto completion mechanism cannot be simply lexicographic—i.e., based on the alphabetical ordering of words. It must consider previous terms that led to successful matches as well as the user’s context: time of the day, geographic location, etc. 

Checkspelling

The prompt should suggest the correct spelling for words that are misspelled.

Related searches and recommendations

The prompt should recommend search terms based on the most frequent searches that follow the current terms in focus. For example, while ‘Customer’ is in focus, the following suggestions might be presented:

• Customer properties
• Customer vs Prospect
• Customer (CRM)
• Customer (Billing)
• CRM migration project

Whenever there is a perfect document view match, the recommended item should directly link to the relevant document view—preferably using an icon that signifies that selecting the item is a link rather than a set of terms to be used in a results page.

Logic operators

The prompt and search backend should intelligently discover whether terms are best treated as ANDs or ORs. For example, if the user types ‘customer CRM migration’, these terms would be interpreted as ‘customer’ AND ‘CRM migration’ rather than, say, ‘customer’ OR ‘CRM’ OR ‘migration’. In other words, the indexing and natural language processing engine would have the notion of N-grams (bigrams, trigrams, etc.) so that the user is not required to demarcate related words with double quotes nor use logical operators unless required for disambiguation.

Question-based terms

Users should be able to express their ‘search’ terms as questions, for example:

• What is the information model for a customer?
• When is the CRM migration project scheduled to start?

If the search engine is powered by an LLM, these questions can be sent directly to the relevant API. Instead, if the search engine is based upon traditional indexing technology, the questions may need to be parsed and reformulated as conventional search terms.

In-place answers and preview

The prompt should provide in-place answers and previews to spare the user from context switching between search and results pages.

Contemporary Search

An enterprise’s documentation system requires a “powerful yet easy-to-use” (Choo, 2002) search capability. Search is not a simple ‘tick-box’ feature in a documentation system, but the primary avenue used to locate most documents.

If search is broken, the documentation system as a whole is broken. No matter how well designed the top navigation bar may be, and logically arranged taxonomies might be, if search is subpar, it is as though all other efforts went to waste. Navigation systems and taxonomies are essential to contextualize a document view so that related information can be quickly identified, but they are seldom used as top-down navigation devices. 

Search is often misunderstood as a “mechanism to find documentation files based on terms that users are interested in”. First of all, users are interested in filling knowledge gaps—not necessarily files per se. Secondly, users don’t know what specific terms they should search for to begin with; coming up with appropriate terms is a burden. The objective of a well-implemented contemporary search capability is thus providing concrete answers or information snippets with the minimal effort and low cognitive load when it comes to term formulation itself. 

Indexing

Search engines do not search directly the internet (or scan a set of files sitting on the file system) every time a user clicks ‘search’. Instead, they scan the internet—or document files in the case of an enterprise—asynchronously, in a process disconnected from the search box.

What a search engine does, when it comes across a page or a document, is called indexing. A search engine has, thus, two fundamental processes: the first one is scanning and indexing, and the second one is searching, which is performed against an index rather than directly on the original documents, as explained earlier.

Indexing is necessary because common terms need to be represented only once in the index for efficiency and storage space reasons. For example, if a hundred documents contain the word ‘customer’, the index will likely contain only one association of the term ‘customer’ to a number, say 52, and then multiple associations of the number 52 to each relevant document. 

While indexing is a well-understood process, it is not necessarily well implemented in some documentation systems. For a contemporary search experience, indexing requires a number of additional features beyond simply building an index of text terms.

First, the indexer should have the ability to index multiple document types and file formats (e.g., PDF, Excel, etc.) rather than only the documents created within the documentation platform itself—for example, wiki pages in the case of wiki engines.

Second, even though the scanning and indexing process is asynchronous, recently added content must be indexed in real time so that authors can search their recently created content immediately rather than waiting because “it’s not in the index yet”. Late indexing—of recently added content—is a significant source of frustration in a number of modern documentation systems.

An advanced indexing engine will also attempt to derive terms that are not directly part of the documentation body. For example, it will also process each image included in the document to index metadata (resolution, color depth, etc.) and infer its content (people, diagram, etc.). It is also not uncommon to perform OCR on all images to produce searchable text terms. This is specifically helpful when indexing documents that use diagrams with text labels.

Search Results Browsing Capabilities

A traditional ‘step two’ Google-like results page containing an seemingly infinite number of links to various pages should be considered an ‘error’ page. Our usability goal is to work out answers and provide direct pointers to document views from within the prompt experience itself. If the user isn’t convinced by the prompt suggestions, only then such a results browsing page would be presented.

A results browsing page should have an experience similar to a hotel booking site. The user is here because they aren’t quite sure as to what they want, and they don’t know what is available either. Therefore, the user experience focus should be on providing smart ways to weed out irrelevant content:

Explicit active filters

Whenever a filter is active, the user shouldn’t require to notice some bold text tucked in the middle of some left navigation bar. All active filters should be ‘bubbled up’ to the top of the page so they can be quickly noticed and removed.

Filter suggestions

Filter suggestions should be based on what filters most other users apply for the same or similar search terms. They can also be determined based on how well they partition large result sets. 

Specialized filters

Each filter dimension type requires a specialized widget or navigation mechanism:

• Standalone labels: stand alone labels are not attached to a taxonomy. The widget should propose the most popular labels and suggest related labels depending on which ones are active, indicating the number of documents that match each label.
  
• Taxonomy labels: when a label that is a member of a taxonomy is selected, the widget should display all child labels for further refinement.
• Dates: date filtering widgets should be more flexible than simply providing ‘date from’ and ‘date to’ input fields using a date picker. First, the date picker should be explicit about the date property being filtered and provide options if applicable. For example, the user may want to search the date of creation as opposed to the date of last modification or publication. The date filter widget should also provide quick data range shortcuts such as ‘last 24 hours’, ‘last week’, ‘last month’, etc.
• Authors: filtering by author should support autocompletion as well as selecting individuals based on a reporting hierarchy, for example, by allowing to search documents created by colleagues or individuals within a specific department.

It is essential not to force any filters or narrowing options onto users before they can search. As Krug (2006) noted: “If you want to give me the option to scope the search, give it to me when it’s useful—when I get to the search results page and discover that searching everything turned up far too many hits, so I need to limit the scope.” 

The results page backend should also run search terms against other searchable repositories both within and outside the enterprise, rather than being limited to the confines of the documentation system. For example:

• Business intelligence databases
• Company bus schedule
• Holidays/strikes calendar
• Office/branch opening hours
• Weather
• Source code management systems such as Git
• Binary asset repositories such as Docker registries
• Legacy documentation repositories such as Lotus Notes or Microsoft Teams

The last thing we want is to force users to open a new browser tab to search for content which could have been displayed within the enterprise’s documentation system.

Large Language Model (LLM) Capabilities

As explained earlier in this section, the main goal of contemporary search is not file location but knowledge gap-filling outcomes. While basic information snippets, and answers which have already been articulated as such in the underlying document (say a FAQ document) may be provided using regular indexing technology, the ability to create well-articulated answers from documents whose content is not phrased in a question/answer format requires a large language model capability (LLM).

LLMs work by repeatedly predicting the next token or word given an input text. Popular services like ChatGPT are underpinned by artificial neural networks consisting of billions of  weights. Given their inherent complexity, most enterprise users are likely to choose a well-established LLM such as OpenAI’s GPT 4 and Google’s PaLM and use them in the form of a turnkey SaaS solution package, such as Azure OpenAI Service or Amazon Q.