The Joomla! Community Magazine™

How to Choose an Extension? Part 3: Documentation

Written by | Thursday, 01 August 2013 00:00 | Published in 2013 August
Is it already time? Time flies when you're writing articles, and it's a close call each time again. I guess that's the same for people writing documentation about their extension. Most of us, as users, just look at the demo, the short description, and then we download and install... But let me give you some reasons why we have to add the step of reading the documentation...

So last time, we had support, this time we're looking at documentation which can be a part of the support given by the developer. If you found an extension from a good developer, documentation is available! Doesn't mean that other extensions where no documentation is available are bad, but documentation can help you a lot.

How? Installation, configuration, troubleshooting, extra fields, behaviors, etc... are all described in a good documentation.

RTFM...

Sometimes we 'forget' to read the 100-page long dictionary somebody wrote... Maybe we don't want to read it, but we should...

Developers who wrote the documentation mainly do this to really show you how to use the extension, what the possibilities are, how to set it up. However sometimes documentation doesn't follow the versioning of the extensions accurately... eg: extension is at version 3 while documentation is still at version 2. Which is understandable from my point of view, sometimes a dev needs to launch the new extension due to a bug, or feature and didn't have the time to rewrite the documentation. Mostly versions are very similar...

A good documentation should have at least four parts. Installation, configuration, customization and troubleshooting.

Installation, is pretty clear what should be described here. And people that are sure that just installing the package by the manager is enough, wrong! Sometimes you need to add, enable or disable some plugins, change a small configuration on your server or php setting... For the basic extensions, you don't need to worry of course, but when you're really adding some great J!-juice to your site this might be needed. I know I had this problem once, and ever since I don't use an extension without any good documentation.

What about configuration? This depends on what features the extension has. A simple newsticker will have a lot less documentation about configuration then a subscribing extensions with lot of extra functions like newsletter, payments, auto renewal, user groups, etc... A good manual covers each step of the configuration, really each step. Maybe it grows by 20 pages that way but better a bit more to read than pulling out your hair... Even if you're not using all the features, read it, you might discover a feature that you will use in the near future or you didn't even know it existed...

The part about customization really depends on which extension you have, some extensions can't be customized (except for overwrites). But if you have chosen one where customization is possible, this part should help you a lot. When I was developing a site with a subscription model, the manual gave me everything I needed to know about customizing the extension and I didn't have to 'disturb' the developer.

And last but not least, troubleshooting, a good documentation covers a lot of the troubleshooting. Impossible to cover all, because we wouldn't need any support then, right...? Issues that occur very often, and always have the same solution are items that should be in the troubleshooting guide. If we as users do something wrong, we still need to submit a ticket because that's not a standard issue...

So good documentation can help us a lot, whether the developer provides it, is his decision. But we as the user, should read it, certainly if the devs have spent a tremendous time writing it... You know the abbreviation RTFM does mean something ;-)

Read 13509 times
Tagged under Sitebuilders, English
Mike Veeckmans

Mike Veeckmans

Just a user , with a serious Joomla addiction !
Mike runs his own company joombiz.eu. The company is focused on Joomla as main CMS. Mike is a sitebuilder, who consults his clients towards successful online business with Joomla. Joombiz also provides sites for non-profit and educational organizations. Joombiz is a rather young company, but took over the portfolio and clients from Mike's former company, which was active for more than 10 years (we started in the HTML/PHP era ;-) ).

He engaged back to the community in 2012 and is active in some workgroups, forums, etc...