Better content starts with better content management. But year after year, documentation teams mistakenly believe they need better writers to solve their content problems. The content management used by documentation teams for years has simply not been up to the task of handling the ever-increasing complexity of technical documentation.
Most content is managed as information scattered across a variety of tools used by a variety of people. This information is published as documents with a variety of formats, and even when a single writer is working with a single version of the information, it can cause problems as other writers update the same information. But the worst problem of all is that the same information is maintained in dozens of places and, until that information becomes outdated.
The structural problem with document-based approaches
As your documentation grows in scope and complexity, traditional document-based methods of creating manual or guides can rapidly descend into chaos. For example, a software company that is documenting the same API endpoint for a developer guide, user manual, troubleshooting documentation, etc. would have to update three documents when the API changes. Unfortunately, this is typically something that never happens.
For example, an API is described in a company’s developer guide, in a user manual or user guide for end users, and in troubleshooting guides for end users. The information is distributed to hundreds of people. As the API changes from time to time, the information in all three documents needs to be updated. In practice, this information is often not up-to-date, causing user frustration and creating a large volume of support cases.
A document-based content management system is, by its very nature, an isolated system. Isolated in that each writer creates individual documents, each containing individual pieces of information. The potential for that information to be inconsistent within individual documents is high. The potential for that information to conflict or contradict with the information created by other writers in other documents is even higher. As a result, individual writers’ work is subject to endless amounts of review and revising as they check and recheck their work against that of their fellow writers. The manual process of publishing individual documents through a document-based content management system creates a lot of excess overhead that can stifle the production of high quantities of quality content.
Component Content Management Systems (CCMS).
How component-based thinking changes everything
In a CCMS, content is viewed as a number of different ways, but generally each piece of information is looked at as individual components or modules of content. These components or modules of content can be single pieces of information or they can be groups of pages of information that get published together. In either case, each of the components or modules of content can then be used in other parts of the help system. For example, let’s say that you have information about an API endpoint in your documentation. That information about the API would be a single component or module of content. Then, if that API changes in some way, you would update that one component or module of content. Then, that single updated component or module of content would automatically get published to all of the locations throughout your help system where that component or that module of content is being used.
Components in a CCMS can also be used in more advanced ways than simply including detailed information about a product or service in a Developer Guide. For example, the same information can also be included in a User Guide and in a set of troubleshooting guides. The different versions of information can then be created and managed as different assembles of the same set of components.
Writer’s can write information without another writer changing their work. Other subject matter experts can review individual pieces of written information. Publisher’s can then compile the information to create a number of different published works without having to re-write the information for each different published work.
A CCMS is really a content library or warehouse that is comprised of individual components of content, not documents.
The complexity most teams underestimate
Changing the way writers work to create individual pieces of information as opposed to complete documents is one of the many aspects that have to change in order to introduce a CCMS within an organization. In addition to selecting the right tool for a CCMS, changing the way writers work, providing the structure of the content that is produced within an organization and implementing the organization’s overall content strategy are key aspects that have to be addressed.
Working with information in separate components or as single pieces of information instead of in documents is the biggest change to the way that writers work when adopting a CCMS. As such, the biggest challenge for most writers will be to get used to working with information in this way, and to develop the skills required to work effectively with information in this form. To this end, the writer will require training and support to ensure that they are able to work effectively with information in the form of separate components or as single pieces of information. All existing content will need to be broken down into the individual components that will make up the new content library. In doing so, it is likely that many inconsistencies and areas where there is a lack of information will become apparent that were not apparent before. Writers may also be surprised at the amount of similar content that they have created before. While this in itself is not a problem, it will highlight that the writer before worked in isolation, creating information that was not used by anyone else, and that the information that they created was not re-used in any other place.
A CCMS introduces a new level of complexity to managing content. As has been stated, content can be stored as components in a library. However, to get the greatest benefit from a CCMS, a team needs to be able to govern the content and to determine if a piece of content is to be used as a reusable component or as standalone content. In addition, there are relationships between components and also dependencies that need to be managed. Organizations considering implementing such a system should first understand what is a CCMS and its implications for their content strategy. An organization is only going to get value from a CCMS if they have the discipline to use the technology properly.
When the investment makes sense
CCMS solutions are most suited for organizations that have large amounts of content that are reused in a number of different places. A software company with hundreds of pages of documentation on a number of different products would be a good candidate for a CCMS solution. The same would be true for a company that has a large amount of documentation that is published in a number of different locations (i.e. intranet, internet, CD ROM, etc.).
For organizations with hundreds of pages of documentation on different products for various audiences, the efficiency in creating documentation will yield enormous returns on investment from a CCMS. For very large translation efforts, a CCMS also has huge advantages over document management systems, since there is less to translate, i.e. single components instead of complete documents. In addition, organizations which create large amounts of strictly compliant regulated documentation will find it easy to keep all related documents consistent with a CCMS.
Implementation reality
The most successful CCMS implementation is one that understands that the CCMS is a system to support a better content strategy. And, achieving that change in processes and how one thinks about content is more difficult than the technology itself for many teams. That requires a tremendous commitment on the part of an organization and their tools, beyond the purchase of the technology itself. There is a lot of training, there are a lot of new processes, there is a re-structuring of the content that already exists in order to take full advantage of a CCMS. That’s the reality.
A change in thinking, in processes and in the way of working with content is needed as well. Training and time to get used to will be required for this. In the end it all works when using the functionality of a CCMS in a structured way and being willing to change processes and way of working. Many teams underestimate the amount of effort required for this.
