Every object in the enterprise possesses latent self-describing properties; thus, the majority of enterprise documentation can and should be generated using automated methods.
Everyone in the extended enterprise—including contractors, partners and customers—are responsible for the creation and maintenance of documentation.
Documentation’s content should be as close as possible to its source in terms of time, content, and medium.
DocOps efforts—the implementation of new technology, and processes—must observe the fact that there is a natural limit to how much information humans can process at one time.
Most documentation in an enterprise should be accessible to the extended enterprise—all employees and partners—by default.
Most documentation should have a human-friendly and consistent addressing mechanism.
Most documentation should be produced for the benefit of the entire enterprise rather than the specific communication needs of a team or domain.
The documentation system should automatically react to changes by updating content, linking to new versions, highlighting deltas, or a combination thereof.
The documentation system should generate documentation in multiple formats automatically, from a single canonical source, without forcing authors to reauthor documents for each format.
The documentation system should maintain document version control automatically, and the capability of selecting versioned documents in a consistent manner.
Documentation should be queryable using a contemporary prompt interface.
The documentation system should empower authors with modern and intelligent document editing and processing capabilities.
The categorization and organization of documentation should be capable of continuous overhaul.
A documentation system should support multiple taxonomies that are independent from file locations.
Most documentation should be produced by composing existing documents, rather than by starting new documents from scratch.
External information should be embedded and seamlessly blended with the relevant document rather than forcing users to look up missing information on external systems.
Documentation layouts should be consistent across the enterprise and not vary by business domain, department, or other arbitrary criteria.
All related information components should be connected, sparing the user from the need of parallel searches.
The documentation system should aim to generate content in a hands-free, mechanical fashion, whenever possible.
Users should be provided with granular semantic and spatial orientation when browsing documentation.
A high-level overview of a documentation system’s key architectural layers.
The heart of enterprise documentation systems.
Conversion between various document encoding formats.
The approach to structure and store electronic documents.
© 2022-2024 Ernesto Garbarino | Contact me at ernesto@garba.org