Flat Namespace

The documentation system tenet of flat namespace states that most documentation should be produced for the benefit of the entire enterprise rather than the specific communication needs of a team or domain. This tenet is a corollary of the uniform addressability tenet but it focuses on supporting the principle of shared responsibility by dismantling silos.

A namespace is an artificial way of segregating content to prevent equally named documents from conflicting with each one another. For example, the Collections, CRM, and Billing domains may have their own Customer definitions as follows:

• docs.allscuba.co.uk/collections/Customer
• docs.allscuba.co.uk/crm/Customer
• docs.allscuba.co.uk/billing/Customer

The most common namespacing mechanisms are folders, domain names, and slash-separated URIs, but applications also introduce their own proprietary metaphors such as spaces, channels, buckets, and so on. In practice though, most users are unaware that namespaces allow duplicate ‘files’. Namespaces are instead used for the creation of documentation silos to segregate projects, teams, and domains.

Engelbart (1990) noted that there was no reason as to why enterprise domains should be siloed or connected with a few lines only, “When do two people in intense cooperative work [each in a different domain] not need total interoperability?”. Engelbart envisaged that as domains become more computer-supported, functional overlap would naturally arise, leading to “all of our basic knowledge-work domains” being integrated within one coherent “organization knowledge workshop”. 

DocOps’ focus is intra-domain and intra-team collaboration, rather than in-silo communication. The notion of documentation being trapped under different namespaces is antithetical to the principle of shared responsibility. Likewise, given that “Information and information skills have a tendency to become fragmented in an organization that specializes in its functions.” (Choo, 2002), we want to minimize such information fragmentation.

It is worth noting that the tenet of flat namespace does not forbid the creation of namespaces. Namespaces are not only recommended, but a necessity—to avoid polluting the default namespace whenever:

1. The content is unlikely to be of interest to anyone else in the enterprise; it does not manifest neither as an input nor an output in any domain interaction. For example, the document view for a debt collection agency called Debt Experts Limited, such as docs.allscuba.co.uk/domains/collections/Debt_Experts_Ltd
   
2. The content is of ephemeral, transient, or informal nature and may not yet be committed to the enterprise’s body of documentation, for example: docs.allscuba.co.uk/domains/collections/_wip/Warning_letter

3. There are a significant number of document views as part of a series—this is common in auto generated documentation. For example:

   • docs.allscuba.co.uk/domains/collections/invoice-3434
   • docs.allscuba.co.uk/domains/collections/invoice-3543
   • docs.allscuba.co.uk/domains/collections/invoice-3555