Content management no image

Published on July 18th, 2011 | by Rahel Bailie


The dirty little secrets of CMS documentation

    Lately, all conversational roads seem to lead to content management systems. Mention a CMS, and someone has a story. Some are good, many of them not so flattering to the CMS. One of the recurring themes lately seems to be how lack of documentation becomes a costly omission.  Installing and configuring a Web CMS is not for the faint of heart. It is exacting work, it is complicated, and it is costly. And when things go wrong, they can go very wrong.
    Getting a CMS without decent documentation is like buying a luxury car that has no windshield wipers. Imagine this scenario – you’re taking possession of your new car. There is a downpour for the first 100 miles. The car salesman tells you that they didn’t get around to putting on windshield wipers because, well, the company doesn’t really think it’s that important. Well, they might have some old, used ones lying around. They don’t really fit, and will leave big streaks that prevent you from seeing properly, but if you insist, they can get some installed. Because it’s only raining for the next 100 miles or so, and then you should be OK. If a sales person tried to convince me of that, I’d be outraged. The reputation of the company would come into question and I’d start questioning the other features. In fact, I’d do everything I could to cancel the contract before leaving the car lot.

    Yet many, if not most, of the mid- to mega-sized content management systems come with incomplete, incorrect, untranslated, and/or outdated documentation. What’s the danger of taking charge of a complex piece of software that’s under-documented?

    Well, let’s start with the integrator needing to do a bunch of extra work. Who absorbs that cost? Is it the integrator, whose developers end up redoing work because they aren’t given all the information they need to do it once? Or do they pass that cost down the line to the customer, who may never know that they’ve just absorbed the cost of bad practice on the part of the vendor?

    Next, there are the project delays. The client waits (and often waits and waits and waits) while the integrator goes back to the CMS vendor to figure out why some feature is crashing, or the system is crashing, or something or other went wrong during setup. The customer, who inevitably has an aggressive launch date, now starts sweating bullets as the clock keeps ticking. And the contractors hired to do various bits with the post-installed CMS  – the content folks who get the content into the new CMS, the testers who are supposed to start running their gamut of tests, the visual designers who are supposed to tweak the CSS and templates, and so on – they get to sit around and wait until the CMS vendor or integrator figures out what went wrong so they can start up their work again. And who pays the bill for flying out a developer from the CMS vendor to troubleshoot what turns out to be documentation that hasn’t been updated since two operating systems ago?

    And then there is the lack of training material. At each level, this is so woefully lacking, it’s a wonder that anyone knows how to operate the system properly. By the way, a few Powerpoint slides showing system configurations and other geeky details is not training. It’s a lazy way of checking off the box for training deliverables without doing the work – and not caring that customers won’t get what they’ve paid for.

    When technical communicators talk about the ROI of documentation, these aspects of project pain seldom get factored in, because no one talks about them. CMS vendors certainly don’t want you to know that their lack of investment in good documentation will cause you thousands, or tens of thousands, of dollars. Integrators won’t talk about the make-work aspects of having to compensate for the CMS vendors’ lack of adequate documentation. And I haven’t met a customer yet that wants to admit they’ve been taken for a ride because it never occurred to them to verify a CMS vendor’s documentation  is up to snuff.

    A word to vendors: Documentation is a product feature! If it’s not an integral part of your feature development plan, you’re not selling a complete product. You should be bounced out of the RFP process in the first round.

    A word to integrators: You have a responsibility to get your hands on whatever documentation the CMS vendor has, as soon as possible, and tell your client where it has gaps. That gives the client the opportunity to go back to the software vendor and make them put the wipers on the car before driving it off the lot into the rain.

    A word to customers: Here are the things you never want to hear from a CMS vendor:

    • We don’t have documentation factored into our project plan.
    • Our software is so straightforward, it doesn’t really need documentation.
    • We can show you our documentation next month, if you insist.
    • We have some documentation, but it’s for the last release.
    • That part of the documentation hasn’t been translated yet.
    • Oh, I can go write you something if you want.
        The era of “real men don’t need documentation” has long sailed into the sunset. Software is too valuable to leave to cowboy coders, and it’s too complicated to send out into the market place without decent instructions. I’m not afraid to demand documentation for software,  just like I’m not afraid to demand all the safety features on my car.  It’s time to get over the idea that documentation is somehow a luxury add-on and consider good documentation a necessity.



    Share this post:
    These icons link to social bookmarking sites where readers can share and discover new web pages.

    • StumbleUpon
    • email
    • Facebook
    • LinkedIn
    • TwitThis

    About the Author

    Rahel Anne Bailie is a synthesizer of content strategy, requirements analysis, information architecture, and content management to increase the ROI of content. She has consulted for clients in a range of industries, and on several continents, whose aim is to better leverage their content as business assets. Founder of Intentional Design, she is now the Chief Knowledge Officer of London-based Scroll. She is a Fellow of the Society for Technical Communication, she has worked in the content business for over two decades. She is co-author of Content Strategy: Connecting the dots between business, brand, and benefits, and co-editor of The Language of Content Strategy, and is working on her third content strategy book,

    7 Responses to The dirty little secrets of CMS documentation

    1. cleve says:

      Great post Rahel and I completely agree. The situation has got a little better over the last couple of years, but there is definitely room for improvement. I’d go one step further and say that all CMS vendor documentation should be online and accessible to everyone, and not just those that have purchased the product. The best documentation also has an open community around it that contributes and shares ideas.

      As you say, I think its down to vendor partners and integrators to push vendors up the documentation hill.

    2. Rahel Bailie says:

      Glad you agree – and I like your idea about social documentation in general, though in the case of a CMS, I don’t know that people who haven’t used the system will have anything to contribute. Though I must say, I like the idea of potential customers being able to read about the pain points of existing customers. Come to think of it, perhaps that’s why there is a reluctance on the behalf of CMS vendors to move in that direction.

    3. Paul Bellows says:

      Rahel, I couldn’t agree more. As an integrator, we often feel the specific pain you describe. There are very few companies that meet the documentation requirements our team has.

      On the flip side, since we work with many of these organizations, there is a constant demand for innovation from customers and I know that most companies work on a 12-18 month cycle for the rollout of new product versions. Since many of these organizations need to maintain their documentation in more than a dozen languages it is extremely time consuming and complex to maintain accurate and detailed documentation.

      I like the earlier post about “open sourced” documentation. It’s certainly one approach, but then who is liable for the information contained there? If a customer writes documentation that turns out to be inaccurate, who is responsible for actions taken based on that documentation?

      I know that one of the companies we work with is attempting to address the problem specifically with a social, open approach to documentation. We’ll see how it goes.

    4. Rahel Bailie says:

      If a company has 12-18 months to roll out new product versions, then they have sufficient time to get the basics down, in my experience. And for translations, they should be walking the talk of single-sourcing, content re-use, and translation memory to make it doable and affordable in a timely manner.

      As for social documentation, customers can comment on better ways to do things, tips and tricks for ways to get more from the software, and correct errors, identify gaps, and so on. That’s very different from having them actually write documentation just because a company has a motivation problem.

    5. Doug says:

      Great post. I do think you mean “faint of heart,” unless one’s CMS is about fencing.

    6. cleve says:

      Re. open documentation, I was definitely thinking along the lines of vendors writing it and the community annotating. However, how-tos and interesting ways the tool has been applied, now that’s community driven and there should be a place to facilitate that conversation that ideally is linked (seamlessly) to the vendor’s product documentation.

    7. web CMS was designed to meet the needs of real business people. It was not designed by developers for other developers like the open source systems available and it was not based on somebody’s perception of what business needed, based on their own experience

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

    Back to Top ↑