Uniform Addressability

The documentation system tenet of uniform addressability states that most documentation should have a human-friendly and consistent addressing mechanism. This tenet supports the principle of low cognitive load—by facilitating the inference of a document view’s topic and content—and truth proximity—by minimizing the proliferation of addresses which may point to stale or incorrect content.

Berners-Lee (1999) noted the importance of uniform addressability prior to inventing the World Wide Web (WWW):

“Once a bit of information in that space was labeled with an address, I could tell my computer to get it. By being able to reference anything with equal ease, a computer could represent associations between things that might seem unrelated but somehow did, in fact, share a relationship. A web of information would form. 

The need to encode the name or address of every information object in some way ‘equal’ [emphasis added] was also essential” 

A uniform address is necessary to integrate documentation in automation workflows and help humans set expectations about the nature of the underlying document view. In the words of Engelbart (1995), “Every knowledge object—from the largest documents, to aggregate branches, down to content units such as characters—has an unambiguous address, understandable and readable by a user, and referenceable anywhere in the hyperdocument system.”

In most cases, a uniform address is implemented using a Uniform Resource Identifier (URI). URI is also the term preferred by Berners-Lee “to emphasize the importance of universality, and of the persistence of information”.

A document view’s URI plays a similar role as the international standard book number (ISBN). In the case of books, it ensures differentiating two different books when they happen to share the same title. In enterprise documentation, it helps ensure that the most recent information pertaining to a given topic is always available using the same address.

Let’s look at a few examples at AllScuba, a fictional scuba diving store:

• docs.allscuba.co.uk/Customer
• docs.allscuba.co.uk/Product
• docs.allscuba.co.uk/_projects/CRM_Migration
• docs.allscuba.co.uk/_projects/CRM_Migration/Sprint_1
• docs.allscuba.co.uk/_incubating/Conversion_to_native_app
• docs.allscuba.co.uk/_archived/Billing_Migration

While this tenet may appear to be stating the obvious, there are a number of unseemingly conventions at play here which set user expectations. The conventions should not be viewed through the lens of  ‘editorial policy’ but in terms of the inferences that users will draw when benefiting from such an uniform addressing mechanism. For example:

Inference 1: All documentation has a home

The domain docs.allscuba.co.uk is the go-to place for all documentation

Inference 2: Key concepts are addressed consistently

All documents follow the docs.allscuba.co.uk/[Topic] pattern

Key concepts are found at the top level: they start with uppercase and are in singular form. All fundamental concepts use the same pattern. For instance, it is likely that the documentation for suppliers is found at docs.allscuba.co.uk/Supplier

If anything changes about the nature of, say, customers, the underlying documentation will change but the URI will stay the same. You can always rely on docs.allscuba.co.uk/Customer to learn anything relevant about who AllScuba’s customers are, how they are modeled, in which systems their data is stored, and so on.

Inference 3: Transient documents are obvious

Non-current documentation—past, in motion, and future—has a lower-case prefix. Document views under the likes of _projects/, _incubating/, _archived/, and so on, do not represent the current AS-IS state of affairs at AllScuba.

You are free to choose any other conventions as long as they are applied consistently throughout the documentation base. What is important is that document addresses follow a consistent pattern that everyone can rely upon.

The second inference, that of being able to address key concepts consistently is paramount in an enterprise documentation system. This notion is more formally referred to as canonical identity.

Canonical Identity

Uniform addressability’s ultimate motivation is the creation of a canonical identity between URIs and topics. Consider the following URIs:

• docs.allscuba.co.uk/Customer_Version_2
• docs.allscuba.co.uk/Customer_Created_by_Mikey
• docs.allscuba.co.uk/Customer_Draft_Nov_12
• docs.allscuba.co.uk/Customers_info

None of these addresses seem to break any rule as far as URI well-formedness is concerned, but they still break uniform addressability by making it unclear what is the address that provides information about customers. When someone searches for ‘Customer’ and comes across URIs like these, the first user’s reaction will be: “Which one is it?”. A proliferation of URIs pointing to similar topics violates both the principle of low cognitive-load and truth proximity.

There should be a good and explicit reason to create competing versions of a Customer’s documentation, which takes to the next related topic, disambiguation.

Disambiguation

Sometimes, we do have different interpretations, or even conflicting descriptions upon the same business object. For example:

• docs.allscuba.co.uk/Customer_Retail
• docs.allscuba.co.uk/Customer_Business

In cases like this, it is imperative to declare a general entry URI docs.allscuba.co.uk/Customer and from there, pointers to the different interpretations, while making an effort to describe the common properties among Retail and Business in the general Customer document view. Likewise, when users access docs.allscuba.co.uk/Customer_Business directly, they should be made aware that this is either a specialization, a different view, or an outright challenging/competing view upon what it might have otherwise been a general Customer description. 

Last, the notion of canonical identity and disambiguation should not be taken as barriers of entry to users who wanted to add to documentation efforts and are now confronted with the choice of an appropriate URI. 

Say that Mikey wants to write some text indicating that he had some sour interactions with a few customers. This is OK. If Mikey wants to have his own take on what an AllScuba customer should be described as—he is a co-creator after all—he is welcome to contribute as long as the URI conveys the less-committal nature of this view. For example:

docs.allscuba.co.uk/_opinions/Customer_According_to_Mikey

Renaming URIs and ‘moving’ Pages

A uniform address establishes a contract between a URI and a certain type of content. A URI is not what a file is named, it is what the content’s topic is about. While it is normal to play around with different URIs while content is being drafted for the first time, once it is released to the world—and by this I mean the enterprise—the URI should not change for arbitrary reasons.

When a URI changes, the former URI should be preserved so that it can point to the new one. If the URI has changed just because a new name is preferred, this can be implemented as a simple redirection, but if the content has changed in nature, then an explanation must be given, offering the user insights upon the alternatives. For example, upon accessing docs.allscuba.co.uk/End_Customer, the user may find an explanation that both docs.allscuba.co.uk/Customer_Retail and docs.allscuba.co.uk/Customer_Business may play the role of end customers, with links to both of them.

Uniform Addressability in Offline Documentation

Uniform addressability is not a notion applicable only to the online world. The tenet of flexible rendering—if adhered to, of course—gives us offline versions of any document. In this case, there would be a 1:1 relationship between each offline document and its online counterpart. Maintaining this link is essential.

In the case of offline documentation that is not directly connected to the online documentation system such as posters, banners, and so on, the concept of key callouts is helpful. A key callout is a reference to documents using a short word without the use of a verbose domain name.

The convention could be, for example, that all keys can be typed directly following the documentation domain name, or that they will lead to the relevant documentation view if typed in in the documentation platform’s search engine.