I'm certain that many of you reading this blog entry has at one time or another tried to install a Joomla! extension or component only to find the instructions on how to make it work are confusing. So you do a Google search for the answer to your question only to be further frustrated because no one has a straightforward answer to your problem. The real problem is that the person who created the instructions for the functionality you are trying to use has done a poor job of communicating.

Joomla! is all about communications and sharing information with others. A lot of the appeal for Joomla! is its ease of use. Make it simple to understand how to use your product.

There is a proverb that says 'he who is wise makes knowledge acceptable'. This simply means that if you are wise you will be able to transfer information, or knowledge, in a way that is understandable to others. If it takes a senior level developer to figure out how to use your product you aren't doing a very good job or doing yourself any favours for all the hard work you put into creating things. You are missing an opportunity to create a good following for your product.

A few years back my wife made clothes using patterns that she bought from fabric stores. She would often get so befuddled because the person who made the pattern and provided the instructions would leave out a step. It seemed like the instructions assumed a higher level of understanding about making clothes than my wife possessed. She was good at making clothes, she wasn't a complete newbie. I can't tell you how many times she said to me; 'I followed their instructions to the letter and when I came to step x the instructions said my project should look like the picture here, and it doesn't look like that at all.' She was right, it didn't. The instructions were missing a step, bad, or simply wrong. Sometimes she would get help from someone else to salvage the project but often it would end there. It would be a wasted effort and materials to boot. She would never buy patterns from that company again. I wondered what was the matter with these pattern makers, why couldn't they make straightforward instructions for their customers?

Ikea makes instructions for the products they sell to their customers. Their instructions are mostly just simple line drawings. They must be doing a pretty good job because they are a very successful retailer. They have figured out a way to communicate well.

The instructions that come with many 3PD extensions and components for Joomla! are often terrible. In Joomla! forums many users are asking for help to install things or how to make them work. They'll point to the product in question and a lot of times even veteran users have a hard time figuring out what the developer is trying to say. English is not always the developers first language but those ones aren't the main culprits. Plenty of English developers are terrible at describing what their product does, how it works, and how you install it. If they did a better job I am certain that they would have a lot more people using their stuff.

Suggestions on how to improve your instructions:

• Think like a newbie. A lot of the appeal about Joomla! is all the great functionality that is available by third party developers. New Joomla! users are attracted to the functionality that you have provided for Joomla! Don't make them turn into a pretzel trying to understand your product. If you are not good at describing step 1, step 2, etc., get someone else to write your instructions for you.

• Pictures help a lot when words make it hard to describe how to do things.

• Videos are even better than pictures to show how things are done.

If you have a support forum then provide courteous help. Don't look down on new Joomla! users. You aren't as smart as you think you are if you can't give easy to understand and efficient instructions about your product. If you find people asking the same questions over and over again then you need to make your instructions a lot easier to find or do a better job of the instructions.

I understand that not every developer has the time to create great functionality as well as promote and educate people about it. Why not get some enthusiastic volunteers who are skilled in the area of writing instructions to help you out? Give them a reason to want to help you. By doing this you will be making things so much easier for yourself and all the potential users of your products.