Technical documentation teams can have different approaches to doing many things. A lot of the stuff can be altered in help authoring, leaving that to personal preference, but when it comes to choosing a place to store user manuals, one needs to be really careful. Today, we will talk about using a CMS for delivering technical docs to readers and why this is not ideal for the case.
It is a good practice to start any research with identifying some terms. Let’s follow this rule of thumb and see what CMS means. Wiki can help: ‘A content management system (CMS) is a software application that can be used to manage the creation and modification of digital content’. Well? This does sound about right and quite fitting for user manuals. If we read further, we can come across more evidence that a CMS could benefit help writers, like, for one, it can support collaborative work. And all kinds of digital content can be embedded including videos, images, maps, etc.
But don’t let this fool you. This might sound promising, but content management systems were actually developed for entirely different purposes. Soon enough you will find many issues if you really try to use it for documentation. Especially when your company is already using some sort of a CMS, it is easy to be misled and decide that this might be a great solution for the doc team. We would like to point out several things you should consider before getting into this whole CMS for documentation thing.
Why CMS Won’t Benefit Your Help Writing Efforts
But before even diving into details, think about this carefully – as stated above, content management systems were not developed to meet tech comm needs. Which means that you will hardly find any solutions targeting your ways of working with documents. Of course, you can try and adapt the tools a CMS offers for your use case, but that would be a foundation built on workarounds. And that’s not good.
When you have a choice between a solution tailored to your needs and something else, perhaps, more general, we suggest that you go with the first option. Now, we did the legwork for you, and here are the main reasons why using a CMS for help and documentation is not the best thing to do:
- User manuals can contain thousands of help topics. In terms of a CMS each topic will be regarded as an individual page. Most CMS won’t have any features to manage such great amounts of pages.
- Each documentation project you have can be unique in many ways. Basically, this is like a whole separate website with different navigation elements, layouts, page design. A CMS allows great control when managing one website, but not many at a time. Again, a tool that actually specializes in helping you manage dozens of different documentation projects (like API documentation, policies and procedures, knowledge base, and so on) will work better.
- A CMS does not understand projects fully. When a documentation team is using projects this means a whole working environment is set up inside: workflows, roles and permissions, style guides, reporting… a CMS won’t let you treat a documentation project as a separate entity. You won’t even be able to publish the whole thing – only page by page. Which makes it really inconvenient.
- Import/export issues. You can’t really import content from Word, HTML, or many other popular documentation formats into a CMS. And, vice versa – a CMS won’t be able to export user manuals to PDF, Word, or Web Help.
- Content review is often a weak side of CMS. If you’re lucky, pages in a CMS will have the Draft/Published state, but that’s it. When working on documentation, you may need more control over statuses, may want to see status-based reports and filters, may need to leave review comments inside of pages, you will definitely need to see a report with unresolved review comments, etc. For web site content, people don’t need powerful review and reporting functionality, but documentation writers rely on this very often.
- Finally, one of the main downsides of using a CMS for help documents – you won’t find any single-sourcing functionality in a CMS. Goodbye conditional content, hello copypasting!
If you are already using a CSM for technical documentation, then you know about everything written earlier and probably wondering what are the better options and how you can move to a different solution effortlessly. You can actually take all your content and migrate it to a help authoring tool of your choice. In ClickHelp this is done by exporting the help topics from a CMS using the following formats: HTML web help zipped, DOCX, ODT, and importing them to your ClickHelp documentation portal. That’s it! No more workarounds and restrictions! You can experience the full potential of working with documentation portal as a service, and stop worrying about looking for ways to do the simplest help authoring things!
Conclusion
The techcomm industry was not always prospering as it is now. We didn’t have many tools that would meet all requirements and allow smooth and user-friendly experience for tech writers. Luckily, the market of software for help writers is blooming at the moment. This is why tech writing teams do not have any strong reasons to look into partial solutions like a CMS to publish their user manuals – there are better ways to create and manage a modern documentation site.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
