Software Documentation: When Git Meets CMS

Software documentation has requirements of its own because software changes constantly and developers and technical writers work with different tools and formats. A modern editorial system must close this gap between Git and CMS on a technical level.

No sooner is a software manual finished than the software has moved on again. Anyone working in technical writing for software knows this feeling all too well. Software documentation covers all content that helps users and administrators understand or operate software, from manuals and online help to API references. This broad field often hides a very specific problem: developers and technical writers effectively work in two separate worlds, with different tools and different formats. As soon as these two worlds fall out of sync, the documentation goes stale faster than it can be maintained. This can have a noticeable impact on support requests and on users' trust in the instructions.

This very conflict runs through the entire article. We look in detail at what causes it, what organizational consequences it has in everyday editorial work, and what an editorial system must be able to do so that it never becomes a permanent problem.

Software documentation differs from classic technical documentation in five ways: constant change, a gap in formats and tools, external developers as an audience, system environments as a variant dimension, and context-sensitive help in the product.

Constant change

New versions and hotfixes replace one another in quick succession, and several development lines often run in parallel. As a result, it is hard to say which instructions belong to which software version unless the documentation was structurally designed for this dynamic from the start.

Gap in formats and tools between development and editorial teams

This is the core conflict from the introduction, and it deserves a closer look. Developers prefer to document where they already work: directly in the Git repository, in Markdown, with branching and merging as a matter of course. Technical writers, on the other hand, need the capabilities of a CMS:

• XML as a structured format,
• reuse of text modules,
• variant control,
• quality assurance and
• translation.

Both requirements are legitimate, but they pull in different technical directions. If the state in the Git repository and the state in the CMS are not kept cleanly in sync, you end up with two versions of the truth instead of one reliable source, with all the consequences for consistency and trust in the documentation.

External developers as a separate audience

As soon as software can be connected via an API or an SDK, an audience emerges that does not exist in this form for physical products. Partner companies do not need operating instructions but reference documentation on endpoints, parameters and authentication, often generated directly from the code.

System environments as a variant dimension of their own

Whether software runs on Windows, Linux, in the cloud or on-premises changes installation steps, configuration options and sometimes entire workflows. This adds another dimension to classic version and variant management.

Context-sensitive help integrated into the product

A machine cannot display tooltips that adapt automatically to the current operating state. Software can. Users today expect help to appear exactly where they are working, for example as a tooltip, in-app guide or chat widget. This also includes cross-links between individual topics instead of isolated single pages. This challenges editorial teams to prepare content that is not only understandable but also machine-readable and modular enough to be embedded in the product itself.

The technical characteristics from the previous section do not remain without consequences. They hit the everyday work of editorial teams directly, and in a way that differs significantly from classic technical writing.

Time pressure from sprints

In software development, short, fixed-length work cycles have long been standard, usually between one and four weeks, with the Scrum Guide setting one month as the upper limit. Requirements are captured, implemented and delivered within a sprint, and the documentation is ideally expected to keep pace. For technical writers, this means they no longer write a complete manual at their own pace at the end of a long project but must continuously deliver small, self-contained units of information, often in parallel for several sprints in several teams at once.

Cumbersome delivery to software-specific channels

Documentation for machinery rarely has to serve more than PDF and perhaps a web help system. With software, API references, in-app help and, increasingly, chatbots are added as output channels of their own, each with its own technical requirements for format and structure. Many editorial systems are not built for the variety of channels typical of software and reach their limits here.

An editorial system for software documentation must bring six capabilities: Git integration with Markdown conversion, variant management, versioning logic, translation automation, delivery to software-specific channels, and a media workflow with automatically generated screenshots. Only then does software documentation work in everyday practice, and not just on paper.

• Seamless Git integration with Markdown conversion. This conflict can be resolved technically without either side having to give up its familiar way of working. A modern editorial system handles the conversion between Markdown and XML automatically in the background and also supports branching and merging. Because Markdown itself has no fixed structural rules, a conversion does not automatically conform to the target XML schema. A good system still allows this import instead of blocking it, and lets the editorial team bring the content into the proper structure afterwards. This way each side stays in its familiar environment, and there is still only one reliable source.
• Variant management for system environments and configurations. The variant dimension mentioned earlier can be controlled through conditional content, complemented by customer-specific service packages, without having to maintain a separate document for every combination.
• Versioning logic tied to software versions and release cycles. Content should be assignable directly to a software version, so that every release is automatically linked to the matching documentation version instead of being tracked by hand.
• Translation automation with a link to UI string localization. The terms used in the software interface should be matched directly against the translations in the documentation. This prevents a button in the software from being named differently than in the instructions, a problem that rarely arises in this form with physical products.
• Delivery to software-specific channels. These channels must be served from a single source, complemented by classic web and PDF, instead of maintaining separate content for each channel.
• Media workflow with automatically generated screenshots and UI states. Display texts, button labels and screen views can be extracted directly from the running software instead of being maintained manually.

If you plan to replace an existing editorial system, the article Practical project plan for replacing CMS and editorial systems offers guidance on how to proceed.

An editorial system that technically connects Git and CMS bridges the tooling gap, but it does not solve everything.

• Terminology consistency across multiple teams remains an organizational task. If every development team works relatively independently, terms and wording drift apart more easily, even if the technical synchronization between Git and CMS works cleanly. This can be mitigated with terminology databases and cross-team standards, but no system can take over this coordination entirely.
• Source code documentation remains the domain of specialized software development tools. They are closer to the code and built to derive functions, classes and parameters directly from the source code. An editorial system should not try to replace these tools here.
• Pure API and interface documentation falls outside what an editorial system should deliver, for the same reason. Here too, specialized development tools provide the actual technical depth. The editorial system complements them at best with context and editorial framing.

Software documentation differs from classic technical documentation not just in degree but in structure. The conflict between the development world and the editorial world, between Git and CMS, between Markdown and XML, is more than a question of tools. It is at the heart of what makes this discipline distinctive. An editorial system that resolves this conflict technically, maps system-environment variants cleanly and serves the right software-specific channels lays the foundation for documentation to keep pace with software development instead of constantly playing catch-up.