ClickHelp Technical Writing Blog
Stories for technical writers, web developers and web designers willing to grow

Content Management Systems for Technical Documentation

Posted by
Anastasia in Technical Writing on 6/3/20204 min read

girl doesnt know banner

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.

girl typing

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:

  1. 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.
  2. 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 documentation projects (it doesn’t matter how different) will work better.
  3. 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.
  4. 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.
  5. 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.
  6. 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!

white laptop and notebook

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

 

HTML Templates for User Manuals
Get This Freebie
Post Categories

Want to become a better professional?

Get monthly digest on technical writing, UX and web design, overviews of useful free resources and much more.
Like this post? Share it with others:
×

Mind if we email you once a month?

Professionals never stop learning. Join thousands of experts subscribed to our blog to get tips, ideas and stories from us once per month.
Learn more on ClickHelp
×
By using this site, you agree to our Privacy Policy and Terms of Use.     Learn more