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

avatar
As a developer AND user (and all developers are both ...) I think doco is vital. It's a pity some developers think that good doco is for those pesky 'users'. The bottom line is it's those 'pesky' users that buy products and learn to love your well-designed and documented solution. Look at forums, reviews etc, in whatever creed, and you'll find unsatisfied users. Nothing has changed (in my 30+ years) because some 'developers' tend to believe they are the 'creator', and writing a manual (no, a good one - not some summary view reflecting the attitude that if you don't know how to use my 'tool' then I'm going to sneer at you.) is below them. I really do wish 'developers' would grow some common (and business)sense.

If you find this insulting then please, RTFM!
VOTES:0
avatar
Except for very simple extensions that need no documentation, the quality of the documentation is usually a good indicator of the quality of the extension.

The best and most popular extensions usually have good documentation and this is no coincidence.

And ultimately, good documentation saves both the users and the developer time in the long term.
VOTES:1
avatar
In the point of view from a Joomla developer, the post is so helpful, it gives me some more understanding to the other side of the customer-provider relationship. Thanks Mike for the post.

Most customers never do RTFM before they facing a real trouble with the extension. IMHO, developers should make the Joomla extension easy enough to use rather than writing 100-page long TFM. This can be done by implementing tooltips or other kinda built-in documentation, the extension can be larger a bit in size, but people don't need to go out-side for reading things.
VOTES:2
avatar
What a lovely instantiation..Very helpful Thanks
VOTES:1