Documentation System

In DocOps Technology, a documentation system encompasses an enterprise’s main general-purpose documentation platform, auxiliary specialist documentation platforms, rendered documentation, systems of facts, systems of dialogue, image sources, legacy documentation, and finally, the DocOps automation layer to integrate all of them.

The center of the an enterprise documentation system is the main documentation platform. The main documentation platform is associated with the topmost documentation subdomain, for example, docs.allscuba.co.uk. The exploration of any key enterprise term, such as the definition of a customer starts here. This is the platform in which the tenets of minimal secrecy, uniform addressability, and flat namespace are realized.

Also, this is the platform in which documentation from multiple sources is composed or embedded and blended, and where all aggregate enterprise documentation is queried, ideally through a contemporary prompt interface.

We then have one or more specialist documentation platforms which provide detailed domain-specific documentation.

One of the first DocOps goals is to ensure the seamless integration between the main documentation platform and the specialist ones. For example, Camunda BPM, a domain-specific authoring tool, may provide in-depth details of an order journey using the BPMN pictorial language, but such process must also posses a formal entry on the main documentation platform in such a way that the formal entry gets updated automatically whenever changes in the specialist platform take place.

Most specialist documentation platforms provide plugins to embed content in one or two proprietary documentation platforms; however, the enterprise might have chosen a non-supported main documentation platform, or multiple render targets might need to be supported, which is not common in proprietary documentation platforms. Whenever multiple render targets are involved, we usually mean off-line rendered documentation in render formats such as PDF.

All enterprises also have vast quantities of legacy documentation in formats such as Microsoft Word either lying on shared drives, or streamed through platforms such as SharePoint or Office 365. A common DocOps engineering task is to convert—or extract content blocks—from such documents to bring them onto the main documentation platform.

We then have the more backend-oriented content sources in the architecture: systems of facts and systems of dialogue. The former provide facts about the past, present, and future state of the enterprise in a structured manner, while the latter provide unstructured—but nevertheless analyzable—commentary. We also have image sources, which complement text and tabular content with pictorial representations, usually in the form of raster or vector graphics. These are divided into primary image sources and secondary ones. Primary ones, such as Adobe Photoshop, have the sole purpose of producing images, while secondary ones produce images among other content types.

Finally, we have the DocOps automation layer whose goals are the realization of DocOps principles and documentation system tenets. The DocOps automation layer may not be a discrete platform (e.g., a dedicated CI/CD engine). It may be crystallized in multiple ways, for example, as a set of custom plugins deployed into the main documentation platform or as cloud functions.