Joomla! We have a problem! It is accepted that the documentation of Joomla! could be improved. We need not dwell on the shortcomings. We would prefer to write about our plan for a new approach and, as we describe the benefits, lightly touch on those difficulties which the proposal addresses.
This article describes an experiment. It will not replace the Joomla! Official Documentation. Only if and when we create something provably, and substantially better, with a clear migration path will a change be considered. This article is intended to stimulate you. If you think there is a problem which we have not addressed, please tell us in the comments space below.
We love your feedback. We need your feedback. We need your help. Please volunteer to help.
Our proposal
1. Use Joomla!
Joomla! Is a Content Management System. Documentation is Content. It is that easy.
- Improved usability – one of the key benefits of CMS is their templating capabilities. We can change the readability of the articles simply by adjusting the template. No longer will you have to twist your neck to read the page.
- Improved search – Smart Search will index the content and that index will be available for searching. Many Joomla! experts use Google to find what they want in the Documentation Wiki. And there is a suspicion that the Google indexing of that wiki is not as effective as it might be.
- Improved structure– We can learn from the success of others. We like the style of MySQL documentation. The essential elements that we like are
- The headline menu will fit with the Joomla! style patterns.
- Selection between versions is available on all pages. But MySQL differs from Joomla! In having more versions and changing more slowly. We will only ever need three versions. And we should expect 6 monthly releases.
- The Table of Contents of the current version is visible on the right and, as you drill into the content, expands to follow your path through the documentation.
- The home page for each version offers several methods to classify the content for that version.
- Each intermediate destination, e.g. 11.3, displays a menu of what is below together with a description of what this branch means and does.
- Search is available for the whole MySQL site, the documentation for this version and something else.
But we also like the PHP on page ability to change languages and their comment option. Try a comment on PHP. We like that.
- Improved internationalisation – The core capabilities together with Josetta allows us to create parallel pages in different languages. This means that if we create thispage.html in English and then translate it to thispage.html in French a user can select the language indicator to move between these two pages. It will not be necessary to pass via the homepage of the Documentation site.
- Easier contribution – The authors of our Documentation will be users of Joomla! They will be familiar with the interfaces and with the methods of using the editors. No need to learn wiki syntax and conventions.
- Easier translation – Using the combination of core multi lingual facilities and Josetta it is straightforward for translation volunteers to contribute pages in their language.
2. Address different user communities
Joomla! Documentation addresses the needs of a variety of audiences. Our effort should foster each of them. We imagine several components.
- Recipes – How do you do something
At present pages are described accurately but the reader is not helped to understand why one option might be preferred to another. The recipes will help a beginner build their first web site and a developer understand how to link to some part of the Joomla! core.
- Explanations – Why might one approach be better than another?
Joomla! is immensely flexible. Wonderful. But to a débutante that is intimidating. They need help to do simple things well and, as they develop, to understand how to do the more complex things.
- Diagnostics – Assistance for the uncertain user.
Experienced technical users of Joomla! have an effective approach to problem solving. Less experienced users may have problems framing their question. Could the uncertain user be assisted by offering links to information that might be useful to them? This is a technical challenge to a Joomla! developer.
- Documentation – The detailed descriptions
The reference manual for those with some experience of Joomla!
3. Define a clear structure.
The structure of the documentation should be, as far as is possible, identical from one version to the next.
Users will learn how to use this structure and, thus, find the structure more straightforward to use. We hope that users will contribute to improving the structure.
The ability to comment on the documentation, although it will require heavy moderation, will provide useful feedback to improving it and its usefulness to users.
4. Build a documentation model for Joomla! 2.5
Build a prototype for documentation of Joomla! 2.5 Our initial effort is primitive and the next version will be expanded in the next weeks and months.
We would appreciate your help in several areas. Email Tony Davis to get access.
- Commenting on the structure we are proposing.
- Contributing content to the pages.
- Commenting on the content as it develops.
- Contributing translations - learn about Josetta while contributing.
5. Construct translations into several languages
Once we have pages we can copy the structure into a foreign language clone. It then becomes accessible to Josetta.
A translator sees the original page and a blank form. We have so far used Google translate to create a draft and then the translator – someone who knows Joomla! And is working in their mother tongue – edits the draft to create a final document.
This is simplistic we know. It is also necessary to replace all the images with equivalent images from Joomla! in that language.
We hope to mark each page in translation with a flag that shows how complete the translation is on a 5 point scale. We believe that a partially completed translation may help someone who is not strong in English understand a point they are finding difficult in English.
If you can volunteer as a translator, please tell Tony Davis.
6. Migrate the 2.5 model to Joomla! 3.0 at the freeze point
But, now it gets interesting.
We plan to have this work finished by early August 2012. WE NEED YOUR HELP.
As Joomla! 3.0 reaches a design freeze point – that is, only minor changes will now be allowed – we follow this process.
- Clone the pages in all the languages into the Joomla! 3.0 documentation
- Copy the images to a Joomla! 3.0 directory.
- Ask the English contributors to get to work.
7. Upgrade the English Joomla! 3.0 model to ensure accuracy.
We plan to treat the English pages of the new version the same as we treat translated pages in other languages. They will carry a flag to show how completely they have been checked as documentation. Are they technically correct? Have they been approved by a language editor? Are the images appropriate?
We hope to have this work completed so that a new English version of Joomla! Documentation is available about two weeks after the release of Joomla! 3.0
8. Follow up quickly with translations.
Translation can begin as soon as the English pages have been checked. The flag on the English page will show how conversion is progressing and the translators can proceed in parallel with their English language colleagues.
We hope to have the first foreign language versions of Joomla! Documentation available about a month after the release of Joomla! 3.0
This is a significant undertaking. It is absolutely clear we will not get it right. But, with your help and support, we will keep making it better.
Joomla! is a community. As a community we can make our favourite CMS much stronger. Please help.
Next month we will write about some of the further implications of this development and offer some specific challenges.