Contextual Wayfinding

The documentation system tenet of contextual wayfinding states that users should be provided with granular semantic and spatial orientation when browsing documentation. This tenet supports the principle of low cognitive load by sparing the user from working out the context surrounding a content subset under focus.

The concept of wayfinding was first introduced by the urban planner Kevin Lynch (1960) to describe the cognitive maps that people create to navigate and understand their environments. In the case of cities, Lynch identified five key elements: paths, edges, districts, nodes, and landmarks. Contemporary UX/UI practice adopts digital equivalents. For example, breadcrumbs and coloured hyperlinks play the role of paths—streets, footpaths, trails, etc. Nelson was also concerned with wayfinding in computer screens, to which he said that one of the greatest problems was “how to make the reader feel comfortable and oriented”.

Wayfinding must be contextual, since “without context, users can quickly become overwhelmed and frustrated” (Rosenfeld et al., 2015). Wayfinding is more nuanced in the case of contemporary enterprise documentation—than public-facing portals—because the relative context—around which wayfinding mechanisms are applied—is not necessarily a document file, but a text fragment or embedded content. 

The specific approaches for wayfinding also vary depending on whether the medium is online or paper. We identify two fundamental contextual wayfinding use cases:

• Intra-document wayfinding: orientation within the current document
  
• Infra-document wayfinding: orientation relative to the entire body of documentation

Let’s delve into each of them.

Intra-document Wayfinding

Intra-document wayfinding is about providing orientation to users within the confines of the current document. Here we use the term ‘document’ rather than the compound term document view because we will also include paper-oriented formats. As such, this applies to any cohesive arrangement of text and images which does not fit into a single screen or page. 

Let’s cover the key mechanisms: progress indication, section navigation, and media galleries.

Progress Indication

As Nelson explained, computer screens, unlike books, lack intrinsic orientation capabilities: 

“In books and magazines there are lots of ways the reader can see where he is (and recognize what he has read before): the thickness of a book, the recalled position of a paragraph on the left or right page, and whether it was at the bottom or the top. These incidental cues are important to knowing what you are doing. New ones must be created to take their place.”

It is essential to provide feedback at all times as to where the user is at relative to the length of the document. We will discuss next some of the common mechanisms to achieve this.

Scrollbars

Scrollbars should be visible whenever a document does not fit entirely into a screen. The middle vertical bar position and size should be commensurate to the user’s location within the document and the document’s size, respectively.

Current page vs total number of pages

In the case of documents that are split into pages, or when adapting the content to a paper-oriented format, it is essential to indicate not only what the current page is, but how many pages there are in total. In printed documentation, including the total number of pages is useful to determine whether there are pages missing.

Progress bars

In the case of larger documents, progress bars may act as a more permanent and intuitive measure of progress than scroll bars. Such progress bars may be configured by the user to show either relative (percent-based) or absolute progress (number of pages, words, etc.). 

Time left indication

Again, in the case of larger documents, it is often helpful to provide users with an estimate of what time investment is required to reach the end of the document. 

Section Navigation

A relatively large document is usually divided into sections such as Introduction, Business Context, etc., which may be defined hierarchically using heading levels. In digital documents, whether a section plays the role of a part, chapter, or sub-section is immaterial. Such semantics may be applied, though, whenever such documents are rendered to paper-oriented formats.

A sequence of sections, when presented as a hyperlinked—or page-referenced—summary, is called a table of contents (ToC), or an outline—we’ll use this term for simplicity. In traditional digital documents, the outline appears at the beginning of the document and then disappears as the user scrolls down. This is a problem. Let’s break section navigation into some of the key mechanisms that help prevent cognitive load and encourage flow state.

Floating outline

In a digital medium, the outline should be visible at all times allowing the user to jump to arbitrary sections whenever needed. 

Current section indication

The user should be aware at all times of the section that the user is currently reading. If using a floating outline, this is typically achieved by removing the hyperlink color from the current section’s hyperlink. On paper-oriented render targets, the current section may appear in the header or footer.

Navigation-bar outline integration

The distinction between document-wise and section-wise navigation is often artificial. If a navigation bar is organized as a specialization of topics, and the outline then further specializes a given topic, then it should continue the hierarchy established by said navigation bar.

Outline on first page

In paper-oriented formats such as PDF it is best to ignore the convention that the first page should play the role of a book cover consisting only of the document’s title, date, and author. While the document’s title, date, and author should indeed be found on the first page, including an outline of—at least—level one headings is key. The reason why is that providing an outline in any page other than the first one forces the user to spend time locating it whenever they need to jump to a different section. This applies both to digital and paper formats. 

Section references

Hyperlinks should not be used to connect documents but also sections within a document. Such hyperlinks should be translated to page references rather than heading numbers when the document is rendered to a paper-oriented format.

Media Galleries

Users process visual information faster than text. The images (and videos) found in a document are the document’s effective cognitive outline for most users. No matter how hard we try to structure a document, most users will scroll up and down—or flick through the pages—until a picture catches their eye. We should not fight, but embrace this behavior.

All of the media found in a document (pictures, videos, audio clips, etc.) should be automatically organized into a gallery so that:

1. The presence of a media gallery is obvious when opening a document view—this is sometimes presented as a film strip but other approaches may also be valid.
2. When clicking on a media resource, the gallery browser is opened, allowing users to browse to flick through all media resources found in the current document.
3. Within the gallery, each resource displays its caption—if provided—and a hyperlink to jump to the place within the document in which it appears.

Infra-document Wayfinding

In DocOps, and a contemporary documentation system in general, the distinction between ‘this document’ and ‘that document’ is fluid given that documents may be easily projected and combined in the form of composite documents and document views. 

Furthermore, as stated by the tenet of connected content, we don’t want to connect files, nor large document views, but relevant, narrowly-selected content. With this in mind, let us discuss the specific considerations that apply to labels, taxonomies, hyperlinks and document references.

Labels

Labels as well as properties—labels as keys with values—are a key wayfinding mechanism that allows the user to find related content. As such, they should not be treated as an accidental detail at the bottom of a page, but as a fundamental navigation device.

Ideally, a document view’s labels should be displayed at the top of the page, or to either side, and indicate the number of document views that match said labels.

Taxonomies

Taxonomies play a fundamental role in helping provide the underlying structure to define all of Lynch’s five key elements. Unlike cities, though, document views may belong to more of one taxonomy.

Given that documentation evolves organically—as stated by the tenet of emergent structure—what constitutes a path, edge, a district, a node, or a landmark may change over time. For example, a small enterprise may not have a billing team; billing may be treated as a function within accounts. In this case, accounts may play the role of a district, while billing may play the role of an edge—or just a path.

In addition, in this text we propose the implementation of taxonomies in such a way that it can support the three navigation systems identified by Rosenfeld et al. (global navigation, local navigation, and contextual navigation) by changing the rendering approach depending on the content’s depth. 

What is key from a wayfinding perspective—and as discussed in the tenet of floating taxonomies—is that we adapt the visualization accordingly to match the semantic hierarchy as closely as possible so that the user is aware whether they are about to travel to a different city, district, neighborhood, and so on. What this means is that, depending on a document view’s location in the relevant taxonomy, the affected visualization may be the main navigation bar, the footer, a floating taxonomy to the side, etc.

Hyperlinks

The humble web hyperlink—when applied to regular text fragments—does not discriminate between links to anchors (i.e., headings) within the same document view, links to different documents, nor links to external sites. As a result, the user can’t anticipate how far he might go when they click on a hyperlink. As Rosenfeld et al., (2015) noted, “as users navigate through highly hypertextual websites, it is easy for them to get lost. It’s as if they are thrown into a forest and are bouncing from tree to tree, trying to understand the lay of the land.”

Despite its downsides, the hyperlink remains an essential feature to connect most information in the enterprise. As pointed by Nelson:

“A business letter will say, ‘In reply to your letter of the 13th…’ Or a business form, another key communication, may say in effect, ‘In response to your order of the 24th of last month, we can supply only half of what you have asked for, but can fill the rest of the order with such-and-such item from our catalog.’ An internal company report will refer to previous reports. All of these citations may be thought of as cross-linkages among documents”

As per the tenet of connected content, we don’t want to create artificial distinctions between content and content containers: what matters is that the content is connected. In other words, in Lynch’s model, hyperlinks act like paths—they can’t provide anticipation as to whether the user is about to jump off district or else.

There are ways to mitigate this, but these all come with compromises that need to be made:

Distinct link color

This approach increases cognitive load because the user has to think ‘why is this color different?’ every time they stumble upon a hyperlink with a different color.

Adjacent icon

A hyperlink may be decorated with a globe icon, for example, to indicate that the link will lead to an external site. Other icons may be used to discriminate between links to headings within the same document versus links to ‘other documents’. This approach also increases cognitive load because the user will inevitably process the visual information conveyed by the icon, which creates a mental interruption between the appearance of the decorated hyperlink and the next word. 

On-hover tooltip

This approach is the least intrusive given that the only cognitive load tax is incurred by the presence of the hyperlink itself. An on-hover tooltip can provide not only detailed information as to where the hyperlink leads but a complete content preview as well. There is one limitation, though, and it is that this approach doesn’t work on touch devices such as tablets.

On-click options

In the case of touch devices, a pre-jump dialogue may be offered when clicking on a hyperlink, which provides contextual wayfinding information before the user decides whether to proceed. This, however, breaks the reading flow state especially in the case of advanced users who are used to a workflow of following links and returning to the main document back and forth.

Document References

When rendering to HTML—which is assumed to be the default in a contemporary documentation system—document references are in most cases hyperlinks. For paper-oriented formats, things are different. 

As mentioned earlier, for the typical enterprise document, page references are preferable to chapter or section references when providing waypoints within the same document. Such page references would clearly convey that the waypoint refers to content within the same document, but what about external documents? There are at least three broad types of off-document references: internal documents, external documents, and public documents:

Internal documents

These are documents within reach of the documentation system. If the tenet of uniform addressability is embraced, it suffices to highlight all terms that have a matching document view. For example, if the word Customer appears in bold, then users can assume that they can learn more about it by typing docs.allscuba.co.uk/Customer. An automatic section called ‘Conventions used in this document’ or similar can be included automatically whenever documents are rendered to paper-oriented formats.

External documents

These documents fall outside the documentation system’s purview. These are assumed to be electronic documents, perhaps hosted in partners’ systems for which direct hyperlinks don’t work unless a SSO session is established. External documents are not all the same, though; they may be HTML, paper-oriented, etc. As such, as per the tenet of connected content, we need to include more granular, content-wise references such as anchors, and page numbers, respectively. 

In paper-oriented formats, numbered references would be an ideal mechanism, but if multiple external documents are referenced multiple times, each time pointing to different content, it is ideal to have a consistent numbering prefix so that the content coordinate can be provided in place. For example: (EX1-Specs, p. 33).

Accidental, one-off references may be rendered as footnotes as well.

Public documents

For informal web references, we can use the same mechanism applicable to external documents. In more formal settings, or in the case of published public documents such as papers and books, it is preferable to adopt an established referencing mechanism such as APA (American Psychological Association, 2019).

It is worth noting that when rendering to HTML, the use of referencing systems such as APA present a challenge. Some public documents are available through hyperlinks—mainly papers—but others such as books are usually not. In order to be consistent, Wikipedia, for example, always links to the reference, and then you can jump from the reference to the web resource, if available. This requires a two click workflow. If we were to hyperlink to the relevant resources in-place, we would then lose the direct link to the reference details (author, year of publication, etc.). Here lies the compromise.

Reflection

Contextual wayfinding is a tenet that requires both general capability support by the main documentation platform, as well as content development care. For example, the main documentation platform must be capable of displaying floating outlines and dynamic navigation bars, while the content must provide the outlines and taxonomies to tell the platform what to display in the first place.

As such, this tenet is equally a document system and a content development one.