ZAP 006 - Topic-based authoring¶

20-25 min read · 5,109 words · View in Zensical Spark

Abstract: The market for technical documentation tooling is currently pulling in two directions. The Docs-as-Code movement favors lightweight markup, Open Source tooling, and developer-aligned workflows, while the Component Content Management System (CCMS) market consists mainly of proprietary, XML-based systems that support topic-based authoring. Hybrid approaches are possible but come with significant integration costs and deeper vendor lock-in.

This proposal is the first in a series of ZAPs to explore how Zensical can 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. By analyzing existing tooling, it maps out the concepts and degrees of freedom that Zensical must support to enable genuine topic-based authoring within a Docs-as-Code workflow.

Take part: We're forming a focus group within Zensical Spark for organizations that use topic-based authoring today – in Flare, Paligo, or similar tools – and are already moving away from proprietary tooling, or actively planning to. Onboarding has started, and kickoff is planned for the beginning of May. Reach out to members@zensical.org if your team is interested in joining the focus group or if you have questions about participation or about Zensical Spark.

Problem statement¶

In modern technical writing, the Docs-as-Code approach is getting increasingly popular. The use of Open Source tooling and workflows widely used in software development helps improve collaboration between product development and technical writing, ensuring that documentation stays up to date and accurate. The practice scales well, as the use of widely adopted Open Source software eliminates per-user licensing costs and frees organizations from vendor lock-in.

At the same time, driven by the need for multi-channel publishing, systematic content reuse, and regulatory compliance (among other factors), the market for component-based content management systems (CCMSs) is also growing, according to market reports.¹ CCMSs are typically provided as proprietary SaaS solutions.²

The market is currently pulling in two different directions: the Docs-as-Code approach is associated with:

• markup light authoring languages,
• decentralization and transparency,
• low-friction Open Source tooling,
• work in cross-functional teams,
• de facto standards driven by the adoption of specific tools,
• automation and workflows aligned with software development practices.

CCMS and other authoring tools supporting topic-based authoring, on the other hand, emphasize:

• semantically tagged, structured data using XML technologies,
• granular content reuse,
• multi-channel publishing,
• metadata and taxonomy management,
• regulatory compliance and auditability,
• technical writing as a specialism,
• formal standards,
• enterprise workflow orchestration and integrations.

While hybrid approaches can be implemented, these come with significant integration costs, doubled maintenance overheads, and, ironically, stronger vendor lock-in due to the use of proprietary CCMS APIs.

In this and subsequent ZAPs, we explore how our vision for Zensical, its differential build runtime, and its modular approach allow us to reconcile these divergent trends and develop a technical writing approach that offers the benefits of both Docs-as-Code and topic-based authoring. In particular, we address the following topics:

Breaking vendor lock-in: By implementing topic-based authoring support directly in Zensical, we enable organizations to avoid or break free from vendor lock-in. The consequent use of Open Source tooling makes it much easier to develop documentation workflows that genuinely fit the needs of a project.

Gradual adoption and flexibility: Following the principles set out in our vision for Zensical, the solution for topic-based authoring will be batteries-included to make starting up a project really easy, provide lifecycle support, and offer degrees of freedom rather than a single opinionated approach. Adopting topic-based authoring is no longer a high-cost, strategic decision that locks you into expensive proprietary products. Instead, your ways of working can evolve organically as your needs change.

Efficiency and performance: Zensical's differential build runtime scales to large projects by systematically reusing intermediate build artifacts and using multiple cores. This speeds up both individual and multiple variant builds. For many users, Zensical's efficiency means they can simply build projects locally or in any CI system. There should be no need to pay for an expensive backend compute infrastructure.

Modularity and extensibility: Zensical's modular architecture and modern design offer easy adaptation and deep customizability using commonly used modern programming languages instead of XSLT. As Zensical is Open Source, there are no limits to the extensibility and to the deployment options.

Reduced total cost of ownership: In addition to reduced licensing fees, Zensical also reduces the cost for customizations through its modularity and runtime support as well by using general-purpose programming languages. At the same time, we will define a set of concepts that allow topic-based authoring to be supported out of the box, so the need for customization is reduced compared to other SSGs.

Purpose¶

This is the first of a number of ZAPs to map out how Zensical will support structured content, rich metadata, and sophisticated content reuse to enable topic-based authoring while benefiting from the advantages of Docs-as-Code workflows. We seek to identify a set of concepts and degrees of freedom for authors that support topic-based authoring practices.

This ZAP reviews the state of the art in topic-based authoring. By aligning with standards like Darwin Information Typing Architecture (DITA) and widely used tools like Madcap Flare, we lay the foundation for interoperability.

We also outline what functionality current static site generators (SSGs) offer and where their limitations lie. The conceptual clarity this work provides serves as the foundation for subsequent work to flesh out concrete use cases and design considerations.