The Problem
Before DITA provided a standard architecture for modular technical content, Cisco's switching documentation organization authored unstructured FrameMaker files and managed them in Documentum. The organization needed to know whether documentation for a complex line of switches could be managed more like code: structured into reusable modules, versioned, branched, merged, and published through a shared system. This was before “docs-as-code” became the common term for that approach.
The DTD was only one part of the system. Cisco also needed to know whether writers could reuse content, manage concurrent release branches, merge changes, produce the required outputs, and work effectively in the authoring environment. Writers and stakeholders needed a working pilot they could inspect before the organization committed to the approach.
Why It Was Hard
A modular documentation system changes more than markup. It affects how writers divide information, what the authoring environment permits, how reuse works, what the system can validate, and whether required outputs remain usable. The pilot used English content and produced HTML and print-ready PDF.
The larger writing organization needed to publish in more than 50 languages. The English-language pilot did not prove the system's complete localization behavior, but it had to establish an architecture that could eventually support that global publishing environment.
The project team included about a dozen people working across the DTD, other parts of the system specifications, and the broader design. Together, the team had to produce enough working software, publishing behavior, and user evidence for a much larger organization to evaluate the approach.
Many writers were unfamiliar with structured authoring and with the practices now described as docs-as-code. They had to explain their needs to developers and IT staff who understood the technology but not necessarily the writing and publishing process. Without someone working comfortably across those contexts, a valid technical implementation could still fail the people expected to use it.
What I Figured Out
The architecture had to be evaluated as a working system, not approved as a diagram.
Prototypes, rendered output, writer interaction, and acceptance testing would expose problems that the content model alone could not. Requirements had to remain connected to observable behavior so a stakeholder could see not only that a design was elegant, but that it worked.
What I Changed
I co-authored the custom DTD as part of the larger project team. Other team members wrote other parts of the system specifications and contributed to the overall design. The system combined structured authoring, reusable content, branching and merging, validation, and multi-format publishing. My work concentrated heavily on rendering, publishing, and prototyping, where those capabilities became something writers could use and stakeholders could evaluate.
My role combined documentation architecture, hands-on coding, and technical project management. I led a three-person rendering team, ran bug scrubs, and managed requirements, priorities, coordination, and delivery. I also worked between the writers, developers, and IT staff, helping writers turn their authoring and publishing needs into requirements the technical team could implement. I translated system behavior and constraints back into terms writers could evaluate, keeping the writing process connected to the code and infrastructure being built around it.
XSLT and XSL-FO transformed the pilot's XML into HTML and print-ready PDF. XMetaL customization, CSS, JavaScript/JScript, VBScript, WebWorks, and related tooling connected the authoring environment to the rules in the DTD and transforms.
The delivery work mattered as much as the code. I built and demonstrated prototypes, supported acceptance testing, triaged defects, created the training materials, led classroom sessions, and helped writers work through the unfamiliar constraints of structured authoring. Their questions and failures revealed where the model or tooling still needed to change.
Formatter behavior was also part of the architecture. We evaluated Antenna House Formatter and Apache FOP against the pilot's PDF and print-layout requirements rather than assuming all PDF engines were interchangeable.
What Changed as a Result
The pilot gave writers and stakeholders a working modular documentation system they could inspect, use, and test. It established a foundation that could eventually support more than 500 writers, the needs of their products, a complex switch portfolio, and many release trains.
Evidence and Technical Detail
Unstructured FrameMaker and Documentum defined the starting point. Custom DTD design, XML, XMetaL customization, reusable content, branching and merging, XSLT, XSL-FO, CSS, JavaScript/JScript, VBScript, WebWorks, HTML, print-ready PDF, formatter evaluation, requirements, prototypes, demonstrations, acceptance testing, bug triage, training materials, classroom instruction, and writer support made the pilot system testable in practice. Broader multilingual output followed later.
