ZAP 008 - Topic-based authoring in Zensical¶

22-28 min read · 5,600 words · View in Zensical Spark

Topic-based authoring systems offer robust content reuse, structured metadata, and variant publishing, but demand high licensing and training costs that make adoption a high-stakes decision. Their extensibility is often limited and adopting them is a major decision that results in significant vendor lock-in.

Docs-as-Code tools lower the barrier to entry and support collaborative workflows, but the indirection, conditional processing, and assembly mechanisms that large documentation teams depend on are available only through a combination of plugins, if at all. This proposal identifies the design considerations for bringing topic-based authoring into Zensical as a set of capabilities that can be adopted incrementally rather than requiring an all-or-nothing commitment.

The central areas covered are: the map format and its relationship to Zensical's navigation-as-content principle; build targets for variant outputs; content reuse at the topic, fragment, and phrase levels; a key-based indirection system; conditional processing and profiling; context embedding; contextual navigation via relationship tables; metadata handling; validation; lifecycle and introspection support; and import and interoperability with existing DITA and DocBook projects. Scenarios serve to validate the approach this ZAP outlines.

Problem statement¶

In ZAP 006, we surveyed existing topic-based authoring systems and identified the concepts they share. We covered the DITA standard, DocBook 5.1, and proprietary tooling. The overlap is substantial and has been stable for some time, which gives us confidence that supporting the union of what these systems provide is a sound basis for topic-based authoring support in Zensical.

However, we do not want to simply replicate existing functionality. The systems reviewed all have significant weaknesses alongside their strengths. When deciding to adopt topic-based authoring, organizations typically commit to proprietary authoring tools or CCMSs. These entail significant licensing, training, and support costs as well as vendor lock-in.

Adopting topic-based authoring is therefore not just a decision about workflows and working practices but also a significant budget decision. Where licensing is on a per-seat basis, growing the number of people contributing to documentation is also a budget matter.

Zensical's goal is to make topic-based authoring a capability that teams grow into rather than a high-stakes decision. A Zensical project can start with a single Markdown file and grow to any size as needs change. It should be possible to incrementally adopt features of topic-based authoring, such as reusable topics, fragment inclusion, key-based indirection, and variant builds. Each of these delivers value independently, without requiring a wholesale restructuring of the project.

To provide this functionality, Zensical will need to implement robust support for structured data, rich metadata, content reuse mechanisms, indirect addressing, and context adaptation. The combination of these features is currently not readily available in most SSGs used in Docs-as-Code workflows. With Zensical, we aim to bring together the best of both worlds: the transparency, low friction, and collaborative workflows of Docs-as-Code with the structured content, rich metadata, and sophisticated reuse mechanisms of topic-based authoring.

Purpose¶

Building on the landscape review in ZAP 006, this ZAP identifies the design considerations for implementing topic-based authoring support in Zensical. The central considerations concern the map format and its relationship to Zensical's navigation-as-content principle (ZAP 004); the definition of build targets for variant outputs; the levels at which content can be reused; a key-based indirection system for robust content reuse; and conditional processing and profiling. A set of scenarios fleshes out the most important use cases.