Most organizations end up picking a documentation platform the wrong way. First, they compare features. Next, they look at pricing. After that, they find that the chosen platform does not meet most of their needs. What looks good in a demo does not automatically translate into real life when it comes to the publication of a large quantity of content.
Companies that get the documentation platform decision right start by looking at the business requirements around workflow and content, and then look at platforms for the specific features they need around those business requirements.
Start with content workflow analysis
The first step is to document your current content workflow. Who creates content in your company? How does content get reviewed and approved? Create a step by step list of the current process for getting content approved. Who are the current approvers? Are any of the approvals automatic or are they all human? Are there specific approval gates (e.g. legal approval for all content)?
Problems in your documentation workflow, which your documentation platform is not solving, will surface during your content workflow analysis. For example, writers at your company struggle with the current process of producing documentation because of versioning problems. Therefore, the documentation platform must support collaboration. Other problems, such as subject matter experts not contributing to the documentation because of the authoring process being too complicated, can be solved by making authoring very easy. Additionally, legal review could be a huge bottleneck at your organization, and the documentation platform must support granular permissioning and include sophisticated review workflows.
By understanding your organization’s current workflow, you can create a desired workflow that your chosen documentation platform will be able to support. This will result in a much more efficient end result.
Identify content types and output requirements
Various types of content need different functionalities. For instance, API documentation can benefit from a platform that supports code, possibly even including interactive examples. On the other hand, a user manual is typically printed, which means the documentation platform also needs to support print-ready formatting for PDFs. A knowledge base is mainly used for search and for discoverability.
Different content requires different features. For example, documentation for APIs with interactive examples and code syntax highlighting is best created with a platform designed for authoring such content (web-based help). On the other hand, user manuals for print are best created with a platform designed for creating print-based documentation (e.g. technical manuals, user manuals). A Knowledge Base, which is designed for creation of large amounts of online content (online documentation, interactive help), will not have the same search and discoverability features as needed for a Knowledge Base.
Evaluate scalability and technical integration
Most platform evaluations are done based on the current needs of an organization. It is not uncommon for simple wiki’s used by 20 person organizations to become a nightmare to manage when the organization grows to 200 employees. Thus, when evaluating a documentation platform, it is best to start by looking at the growth trajectory of the organization over the next two years. Will you need to create many different output formats (e.g. PDF, HTML5, etc.)? Will you need to publish in localization languages (e.g. Spanish, French, etc.)? Will you need
The needs of documentation will grow with the size of your organization. What are your growth plans for the next two years? Will you need to support, for example, multiple output formats? Will you need to support documentation in different languages and regions? The expensive thing to retrofit is the integration with other customer facing tools, such as customer support, e-learning, etc.
It is important to consider the technical integration capabilities of any documentation platform. The best documentation platform is one that can seamlessly integrate with the other tools and processes your organization is using. As a result, it is very important to avoid platforms that will require you to start from scratch. Look for platforms with robust APIs, support for Single Sign On (SSO), integration with version control systems, and more.
Test real-world performance under load
Most platform demos are created to only show off a very limited amount of content. Rarely do demos have more than a handful of documents or even a couple of pages of sample content. It is not until you load up your own content that you can get a true sense of how well a platform will perform. Importing your existing content into a test environment is a great way to find out how well a documentation platform will work for your team.
Test the functionality of the documentation platform for your large amount of content. Find out how the search function works. Often demos are created with a very small amount of content and search appears to work fine. Later, when you return to your work and start to create more content, you may find out that search does not work as well as you had hoped. This could be due to lack of consistent terminology or formatting.
Consider the total cost of ownership
When selecting a documentation platform, consider all the costs that go above and beyond the annual license fee. The cost of a migration to the new platform, the time it will take to train employees on the new documentation tools, the on-going maintenance, the cost of any customization, etc. For example, a platform may cost more in the first year more than another solution on the market, but cut the time a writer spends on formatting and publishing content by 80% and therefore be a better long term solution.
Note the large license fee for this documentation solution? This solution saves your writers up to 20% of their time by automating the formatting and publishing for you! If your writers currently spend 20% or more of their time formatting and publishing content, then automating these processes could save them a significant amount of time. This could, therefore, justify a very large license fee for the solution.
Unbeknownst to many organizations, there are substantial hidden costs to the free and low-cost documentation platforms currently in vogue. The cost of free, open-source documentation tools such as Confluence, Wiki Spaces, and others is not merely that of feature and functionality comparisons among competing solutions. The cost of support for these tools is substantial, even for straightforward authoring, managing, and publishing of content. For organizations with large volumes of content over time, the cost of workarounds to support increased volume to be developed by IT support staff is very substantial.
I read recently that MadCap Software, maker of the high-end documentation platform Flare, makes a fortune documenting the total cost of ownership for “documentation platforms” for large numbers of large enterprises. What they typically find is that the up-front license fees for their documentation platform get more than paid for by the costs of the organization’s current process for documentation, especially where a large part of a writer’s or reviewer’s time is spent on formatting and publishing. So, for example, if a writer spends 20% of their time on ” publishing” and you switch to a system where that time is cut in half, you could likely pay more for the expensive documentation platform license fee.
Plan for change management and adoption
Even the most powerful documentation platform will not add value if your team is unwilling to use the software.
When choosing a documentation platform it is not only important to select a tool that fits your workflow but also to have sufficient change management in place. All stakeholders involved in the evaluation process of potential documentation platforms should also be involved in the process of selecting a tool. Writers and reviewers are more likely to invest in a new documentation platform when they have selected it in the first place. In order to get your writers and reviewers invested in shape to select the best tool for your organization, you can start by running a pilot with a couple of projects. This will give you a good idea of whether the tool will be suitable for an organization-wide implementation or not. Also, it will help you and your team to get familiar with the interface and find out whether you will be able to work efficiently with the new tool.
Not all documentation platforms are equal when it comes to ease of use. Therefore, when selecting documentation platforms it is essential to consider not only the potential training time required to get started with a new platform but also to take into account your writers, your organization, and their ability to learn new tools.
So in summary, whatever documentation platform you decide to use for the next few years, it is worth spending the time to getting the workflow, technical and adoption issues right. If not, the chosen solution will end up being more of a hindrance for your team and their content generation efforts rather than being of assistance.
READ ALSO: Reliable ITAD Manchester Services for Secure IT Equipment Disposal
About the Author
