How to Write Helpful Joomla Documentation.
Get on your Joomla Bike
Want to learn to ride a bike? Let’s find a book. Have you ever seen a book on learning to ride a bike? I haven’t, although there is one.
Perhaps the most surprising thing about this book is that it describes a patent pending method. Really?
Like many things in life you learn to ride a bike by doing it. Attempts to formalise that process meet ridicule. A British newspaper pokes fun at the police who produced a manual about it.
But you want to learn Joomla. What are you expecting to find?
I would really like to know and would be pleased if you would tell me by leaving a comment.
Why am I interested? Because I am considering what kind of documentation Joomla deserves and there is a bit of a problem. Let me explain.
As someone who taught for many years the important thing to get right is to understand your audience. For me, my audience was mostly medical professionals or students training to become one. Clearly anatomy for surgeons is more detailed than anatomy for care assistants. And, teaching in London, attention had to be paid to the language skills of the student. Obvious when you know, but those who study only from books do not know the sound of
?-carotene – pronounced beta carotene – so that is a term which needs to be used with care.
Those problems exist for the documentation of Joomla.
- The audience ranges from total beginners with no technical skills through skilled developers who would like to add features to the Joomla universe up to advanced programmers who contribute to the core of Joomla.
- And more than half of those who use Joomla do not speak English although the single largest language group is English.
- Finally, Joomla uses some English words with special Joomla meanings.
Above all there is one big difference between my medical trainees and the learners of Joomla. The medical trainees expected to read lots of it in books and to learn the book so that they could – nearly – recite it. On the other hand, Joomla is so straightforward that there is a great temptation for the novice Joomlateer to dive straight in and then look to the documentation to help them escape from problems they encounter.
In contrast to the single book on learning to ride a bike, Amazon lists 28 on learning Joomla.
For a teacher of anatomy the challenge is straightforward. Write a clear description of your topic, illustrate effectively and publish. If it succeeds in your language look to translate it to others.
The documentation of Joomla is a volunteer project, there are many contributors although it would always be good to have more. Cat herding is always difficult. Cats prefer to come to something attractive. How can we make the project attractive to our volunteers?
That is not a question that anyone has a clear answer to. But this is a proposal and we can test if it works.
The proposed Joomla documentation will be
- Definitive – It should be closely tied to the development road map
- Didactic – It should be the authority on how to use and develop Joomla
- Demonstrative – It should show how things are done. Certainly through the use of recipes, images and videos – but what else?
- Diagnostic – It should allow rapid access to relevant material by describing your current problem. Do you know how to do this?
- Complete – It should cover every aspect of Joomla. Contributors of new extensions should be encouraged to contribute documentation simultaneously.
- Clear – Short sentences using simple words.
- Concise – Short overall.
- Conversational – Every section should encourage comment, feedback and improvement. Care will be needed here if a section is useful to a heterogeneous audience.
- Assisting – Words with technical meaning should link to tooltips of brief explanation and a glossary for more detail.
For its authors there should be facilities for
- Versioning – To allow roll back
- Multi lingual versions built in.
- Templated – to encourage and/or enforce consistency
- Efficient – A virtue of Joomla is the use of consistent design principles. Once reference has been made to a design pattern that piece should be available for use wherever it next appears.
- Moderated – Language editors for each language should attempt to produce a consistent voice throughout the pages.
Can we achieve that? Please let me know what you think.
And what a marvellous demonstration it will be of the power of Joomla – the best CMS in the world.