How can documentation software improve content production?

Yes, Content Teams can fail, but generally not because they cannot write. Repeating the same paragraphs in 9 different places, distributing reviews in email attachments, spending afternoons sending one single corrected sentence to 4 channels, these are the problems documentation software solves. Results of its usage are expressed in terms of cycle time, translation spend and defects found in documentation, not in word count.

Authoring efficiency comes from constraint, not from faster typing

Content that is organized in a certain manner through component content management systems or through the use of structured authoring tools actually speeds up the actual writing process in several critical ways. Primarily, such content structures actually remove a host of decisions that would typically have to be made by the writer of said content. Thus, for example, a task topic that includes a short description of the task at hand, as well as the prerequisites to performing said task and a step by step description of how the said task should be performed by the end user, allows the author of said document to immediately begin writing the steps to complete the described task, as opposed to having to first decide upon an appropriate format for said steps.

When the content is separated from the presentation (the visual layout) then the writer is able to focus on the real quality aspects of a piece of content, such as researching, organizing, determining what content to write in the first place. All the time spent setting up tables, deciding upon the placement of the section break, determining the optimal length for the article to fit on a particular page etc. Are not quality activities and can be performed by others prior to distribution.

Where the time actually goes

• Formatting and layout work, largely eliminated by publishing pipelines that apply styling at output
• Locating the current version of a topic, solved by a single source repository with clear ownership
• Rework after review, reduced when validation and linting catch structural and terminology issues automatically
• Manual cross-referencing, replaced by managed links that survive reorganization

Reuse changes the economics of every downstream activity

Re-use is generally the biggest ‘sell’ for structured documentation. However, this is often ‘sold’ in the wrong way. Use of variables and conditional text to enable fragment level re-use of items such as product names, version numbers and safety warnings is commonplace. However, it is rare that there is sufficient thought given to the higher levels of re-use such as topic-level re-use of identical content (e.g. An installation procedure used in an administrator guide, quick start and knowledge base article) and map-level re-use of topic-organized content to create entirely new publications for different audiences and at different product tiers.

The impact of this though, is that even though you are only writing a single topic, that same topic will be used in many different deliverables to many different audiences. This is why translation savings are by far the biggest gain for companies shipping in more than 4 languages – as long as they have been written with reuse in mind and not as an afterthought.

The condition attached to reuse

This means that each single piece of content must be written to be as context-independent as possible and therefore not start with a reference to previously written content (e.g. “As previously described…”). The scope of a single piece of content has to be clearly defined within the team’s modular approach. Within this modular structure there are strict rules for linking between topics as well as for the use of conditional text.

Consistency becomes a system property rather than an editorial burden

Automated checks for style guide compliance are notoriously hard to set up but once you have set up your style guide as software then all of the terminology in your terminology database will be flagged up whenever a writer uses a banned or deprecated term. A controlled vocabulary for metadata search, filtering and conditional publishing will also be checked automatically against the values in the metadata fields for things like images. Is all image alternate text set up correctly? Do all step descriptions start with an imperative verb?

In highly regulated industries such as aircraft documentation or financial services, even greater consistency in information management is required. With a versioned repository for documentation approval it is easy to document who made changes to a document and when these changes were made.

Publishing multiplies the return on everything upstream

Furthermore, teams that need fully responsive online help generated straight from structured content are usually well served by MadCap Flare software. In addition, structured content can be used for printed documentation (e.g. For sales) and even for in-product help. A large volume of chatbot-utterances can also be generated from a single source of content and subsequently updated with a single change as required.

Comparing common approaches

Sequencing the change so it holds

Migration = very long and painful file-conversion projects. This works way better when done in reverse order.

1. Audit existing content and retire what no one reads before converting anything
2. Define the information model, topic types, and metadata scheme with input from support and product
3. Convert one substantial deliverable as a pilot and publish it end to end
4. Measure cycle time, translation volume, and support ticket deflection against the old baseline
5. Expand only once the pilot numbers hold across a second team

It takes 6-12 months before any return on your documentation investment is shown. This is because of the time and effort involved in developing the information model, the appropriate editorial standard(s) and in getting writers to deliver single topics of high independence. This has to be factored into the overall budget for the tooling.