The dirty little secrets of CMS documentation

The dirty little secrets of CMS documentation

by Rahel Bailie

July 18, 2011 · Posted in content management · 2 Comments »  

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 feint 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.