Principle of Generative Content

The DocOps principle of generative content states that every object in the enterprise possesses latent self-describing properties; thus, the majority of enterprise documentation can and should be generated using automated methods.

In DocOps, this principle is based on the realization that most facts about an enterprise object can be queried or extracted. No one has to write ‘a document’—necessarily. As explained by Zuboff (1988):

“Computer-based information systems not only process data but also generate new information that describe, explain, and summarize the operations they automate. By rendering visible the rules, assumptions, and constraints that are embedded in the automated operations, this ‘informating’ ability of computerized systems allows employees to learn a broader and deeper view of their work activities”.

Even if the object is in motion—it hasn’t been agreed upon, or its very existence is under debate—then that means that it exists in an explicit known state of confusion or ambiguity.

Documentation as an Extractable Property

DocOps sees the problem of documentation gaps first and foremost as an extraction problem rather than a ‘typing’ one. Most mature enterprises generate business reports automatically; data is extracted from databases and pie charts are generated from data. Most ‘regular’ documentation can be generated using exactly the same principles. 

Nearly all business activity is conducted electronically today; software is no longer eating the world, it already ate it (Singh 2019). The bulk of an enterprise’s documentation needs can be generated by querying the systems of facts and systems of dialogue that already exist in the enterprise.

This notion of documentation as an extractable property also applies to informal business communication—rather than just the realm of formal project management and software development. Video conferencing applications such as Zoom can be queried to obtain transcripts. Messaging applications such as Slack already operate in a text medium. In most cases, there is no longer the need to write ‘meeting minutes’ or similar documents. Transcripts can be summarized using Large Language Model (LLM) technology automatically.

Documentation as an Intrinsic Property of Software

It took a long time, but most modern programming languages such as Go and Rust assume that testability is an intrinsic property of any code bases created with such languages. While developers may opt for different testing frameworks methodologies, the de facto expectation is that by running go test, or cargo test, respectively, the application will self-diagnose itself for faults. Of course, such a self-diagnosis needs to be implemented, typically in the form of unit tests, but the point is that in this day and age, the de facto expectation is that all software is bundled with test cases and, most importantly, that running such test cases is as natural as building the software itself.

The unit tests that run when these ‘test’ commands are executed are an inseparable part of the software’s codebase. They are not ‘products’ to be delivered by a separate QA team, or an optional aspect of the software which may or may not be delivered. In the case of software, DocOps treats documentation in the same way; as a natural, intrinsic property, rather than an external product.

Producing documentation out of software should be as natural as implementing and running test cases. It should not be a philosophical choice between frameworks and methodologies. Ideally, ‘go docs’, or ‘cargo docs’ should do the job—in the case of Go and Rust—but we are not quite there yet, so this makes it a DocOps’ job for the time being.

Two Meanings

As the reader might have noticed, the word ‘property’ has two meanings in the context of generative content. 

The first meaning is property as data or structural information that is inherent in all business applications: systems of facts (CRM, ERP, etc.) and systems of dialogue (Video conferencing, messaging, etc.). We can construct the bulk of our enterprise documentation by querying relevant properties from systems that are already in place. This principle does not forbid human contributions; what is emphasized is that extracting information is preferable to copy-pasting it or retyping it. 

The second meaning—as a consequence of the first observation—is that all enterprise products and endeavors should have documentation right from their inception even when little is known in the beginning.

Reflection

Over a decade ago, implementing an API and creating developer documentation for it were two disconnected processes. A software engineer would implement the API, while a technical author would write a document enumerating each API together with its requests and response signatures. If examples were included, the technical author would make them up—if they didn’t have access to a live system with test data. This situation resulted not only in documents containing errors in the API signatures, but also in broken sample requests and responses.

Today, both the software interfaces and documentation for web services APIs are generated automatically from what is known as an OpenAPI specification—formerly called a ‘Swagger spec’. Tools such as SmartBear’s Swagger Hub generate complete documentation portals out of such specifications. 

DocOps vision is that documentation for the entire enterprise should be produced in the same way that Swagger Hub does for APIs. Having said this, while DocOps aims to extract documentation properties from all systems, and generate documentation automatically, we still need ‘original content’ created by humans—OpenAPI specifications, for example, do contain human narratives in addition to formal API properties.

Original content does not compete with mechanically-generated content; they are typically intertwined in composite document views, just like Swagger Hub’s documents do. Because original content will still remain key for the foreseeable future, DocOps focus on ‘people and process’, rather than just technology is paramount. This takes us to our next principle.