Tips on Decent Joomla! Documentation
Written by Lilit Asatryan
Lately we have been experiencing some issues of not having a proper documentation. You know when we just started creating our templates, we did not realize how crucial having a decent documentation can be. We learn as we grow. And our users are the ones who teach us many things. So thanks everyone who has been paying much attention to what we do and moreover, point to what we lack.
We always strive to bring the best for our users, so as we get more experienced in what we do, you might have noticed that we change some certain things.
As I am writing this blog post, our developers have already started sketching some outline of documentation. If you are one of our users, then you know we do have documentation. But it seems not to assist the needs and solve the issues our users have been experiencing. So, we decided to give it another try and do a research first to know the tips and tricks of what a good documentation should consist.
The moment when a developer is done coding the template, he feels relief, however, that's where another work begins - documentation. It's important to get started with documentation right away trying to provide some answers to possible questions a user will ask. So, in documentation you should clearly define how to use your product so the user will have few questions left to ask.
A good documentation saves time!
If you do not want users coming to your forums not even trying to search before and asking same questions, then a well-written documentation is what you need. When a user plays with a template and something goes wrong, he will definitely look for documentation just before asking you on forums or via ticket system.
Provide detailed information on what to do and how
First of all, think about the chain of the steps they will go through and try to give answers for each step separately. For instance, the first step when a user successfully downloads your product is the installation process. Clearly define 1, 2 steps a user might need to go through to have the template properly installed.
Another important thing is to tell the user what he/she needs to enable, disable right away so not to have problems afterwards. If you have got some advanced options, tell about it a bit later. Make sure you mention the basic steps first.
Installation: Think Joomla!
You never know if your template is the first acquaintance a user is having with Joomla! So think of a level of Joomla! knowledge a possible user will have. Do not think that a user will know Joomla! as you do, never, go in details and explain in a simpler way possible. So, describe the installation procedure, and or provide a quality resource on it. It might be a tutorial you made or another great tutorial from a community member, link to that source.
Use your time wisely
Most likely all the developers do not even think that even the smallest things like explaining what a certain button or drop down menu do a user will need to be explained to. Guess what? They do! So go into details thus saving more time for you to spend on development rather than on support answering silly questions which could have been answered long ago in your documentation.
You have probably read my blog post on how Images are important for SEO,and how important Catchy blog picture is, so keep in mind, images are very important – full stop. Let your documentation be visually explicit, include some pictures explaining where this or that function is, or where the user can find the needed option in drop down menu.
Can your grandma understand this?
Sit down and ask your relative or friend who is a far from IT to read and see if he can understand your documentation. If the answer is YES, then you did a great job. If not, ask what points were confusing and edit them. Never ever ask your coworker or an IT person to read your documentation, that' snot going to be helpful.
Show them what you got!
Yes, most of the times, people watch the product to see it in action. So, include a technical tutorial which will somehow cover the main functions and guide the user through precise steps in the back end to see the result on a website
Review your documentation from times to times
Ever had to explain same issue to a lot of people in your forums? Then you have got a problem. Read carefully what the issue is all about and try to explain it in a decent way possible in your documentation. Renew it and edit it, save both your and your users' time and energy.
"I am done!" said the developer
No, remember , you can never be done with the documentation as with every new update and version you will be getting many support questions, so be prepared for this. However, what you can do, is to link to your documentation id you think that a person is asking about an issue which is already stated in your documentation.
We all have to admit that most of the times, users do not even care to read the documentation, so make as simple as possible. Link to certain parts of the documentation if you feel like a user is asking about it but he/she did not find it somehow. Also pay attention to some sections which you are going to have for every extension. Either make your points clear or show them visually, make a video for these general parts and have them included in every coming extension.
These are some highlighted tips on writing decent Joomla! documentation that I have come up by researching and simultaneously starting the documentation for our extensions. Please, stay tuned as Bang2joom is going to include some great documentation for our extensions and ease our users' lives.