CMS: workflow as a bonus, but reliability to be tested
A CMS like SharePoint or Alfresco adds workflow and file-locking to technical writing, and some (DocZone, Componize) even handle DITA XML - but their reliability for archiving source files must be tested and backed by a solid backup strategy.
Definition
Section titled “Definition”The CMS, often termed this way for marketing purposes but more accurately described by the acronym EDMS, introduces workflow and link management features that are invaluable for handling modular documents.
Key principles
Section titled “Key principles”When using monolithic formats such as FrameMaker, technical writers can employ a CMS (Content Management System)A tool that adds workflow and file-locking to content management, at the cost of reliability trade-offs compared to plain version control.View in glossary → like SharePoint, Alfresco, or similar systems (as an alternative to a single Git repository) to:
- download a local copy of shared files to their hard disk,
- make modifications to the local copy,
- upload the modified copy to the central RepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary →.
This approach is more efficient than using a simple file server, primarily because file transfers over the network are less frequent. However, it remains necessary to lock files being modified, a task managed by the CMS.
While originally designed for monolithic documents, many CMS solutions now accommodate the modularization of technical documentation. Systems such as DocZone or Componize, the latter built on Alfresco, are specifically designed to manage modular documentation using the DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → architecture.
Trade-offs
Section titled “Trade-offs”How can we be sure that solutions updated this often - frequently for commercial rather than technical reasons - stay consistently reliable?
It’s prudent to exercise caution when relying entirely on them for managing and archiving documentation source files. A careful selection of the solution is essential, paired with a robust backup and restore strategy.
The docs-as-code alternative
Section titled “The docs-as-code alternative”With text-based Source formatThe format content is authored in, as distinct from the target format it's published to — the recipe versus the dish.View in glossary →, a Version controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary → system provides most of what a CMS workflow is chosen for, without file locking:
| What a CMS workflow is chosen for | What version control provides |
|---|---|
| Parallel work | Branches let several writers work in parallel |
| Review and approval | Pull requests carry the review and approval steps |
| Traceability | The history records who changed what and when |
| Archiving | Every clone of a Git repository is a full copy of its history, which addresses part of the archiving concern |
See integrating documentation into development processes and the review workflow example.
A CMS remains relevant when contributors cannot work with text files and version control, or when the organization already relies on one for other content.