Systems Documentation

Photo of author
Written By Ryan Rana





One of the aspects of open source Content Management Systems that is often overlooked is the documentation.  It stems from the fact that the developer often has to try to cram as much as possible into a project for the client’s given budget, and at the end of it they just want the job signed off and delivered.  The documentation aspect gets given scant, if any, attention.

The trouble is that this often undermines the entire project.  A CMS that the client isn’t able to add content to, doesn’t understand, is scared of.  The client has paid for this wonderful CMS that they can’t use, and the site’s content stagnates and ends up out of date and irrelevant before too long.

It’s important that effort is made to create systems documentation that has been tailored to the client’s specific system and I think it’s also important to make a specific line-item provision for this in the work order (i.e. not just bundled in with the rest, but split out as a separate item).   That way you can’t just tack it on, you have to spend the required length of time creating proper documentation.

As a developer you end up building up a comprehensive library of systems documentation for all kinds of systems, extensions and plugins.  You can cut down on the time spent tweaking it for the client.  And of course the more you do, the faster and better you get at writing it.  The client can reference their own systems document again and again, and work through it at their own pace and in their own time.

Which brings me on to my next point. Face to face training is an utter waste of time.  The time is much better spent on comprehensive documentation full of screenshots and explanations. During a face to face session the client will take a few scribbled notes, nod their heads vigorously as you explain things, and then breeze through the examples you give them.  A week later they will have forgotten everything you’ve said, will look in incomprehension at their own notes, and be on the phone to you asking to talk them through the process again.  Poor value for money.

One last point about handing over a new system. Have a version of the site on a subdomain somewhere, allowing the client to harmlessly play around with their new toy in a sandbox environment.  They can do what they want without fear of breaking anything or having their experiments visible to the world on the live site.

A client who is confident with their own system will make the most of it, and make it a success.  As a developer you want your projects to be commercially successful, the benefits of this will filter back to you over time.

Categories CMS

Leave a Comment