Joomla! Documentation Concepts

Should Joomla! Documentation be better?

Is this where you find how to use Joomla?

Joomla! is used by more successful web sites than any other CMS. You can find lists of government users, showcases of what others have done and statistics on Joomla! use very easily.

There is a very good reason for this. Joomla! is built in such a way that means it is both easy enough for beginners to use and flexible enough for seasoned professionals to shape it to their wishes.

But beginners meet pain when they begin. In particular, pain is experienced by the halfway man, someone with a little knowledge of PHP and MySQL, who tries to modify or adapt Joomla!  Without reasonable experience this path will fail. The trick is to use Joomla! as it is intended. Go with the flow.

The Documentation fails Joomla!  There is a ton of excellent material there. It is written clearly in English. But it is a place where those who know where to find what they are looking for do better. I know a wonderful restaurant but it is hard to find!

The aim of our work is to create Documentation for Joomla! which will satisfy the following needs.

  • Descriptions – what do you find on the various parts of Joomla! and what are they for.
  • Recipes – how do you achieve specific things with Joomla!
  • Explanations – why would you do one thing rather than another in Joomla!

And these needs should be in many languages. English is the core language of Joomla! but more than half of the Joomla! community have another language as their mother tongue. They should not be ignored.

Symbols and Icons will assist in indicating where help can be found. We would love someone to offer a set of icons to achieve this in a way that will suit all languages and cultures.

In July we will link to the new article in Joomla! Community Magazine.

Categories: Joomla Documentation | Leave a comment

Joomla! Documentation – Feedback needed

Could you tell me how you think Joomla! documentation could be improved?

I am interested because I want to design a new approach. The new approach would

  • Make it easier to find what YOU are looking for
  • Make it easier to manage
  • Make it easier to translate

Just a pipe dream?  I do not think so.

Can I do it by myself? Absolutely not. But the Joomla! community is just that – a community.

So how do I plan to set about it? Like this -

Make it easier to find what you want.

In a previous post I looked at MySQL and PHP documentation. These are easier to use than the Joomla! documentation and we can learn from them.

Make it easier to manage

The current Joomla! documentation is based on a Wiki. There are good reasons for that – especially when the documentation was initially developed.

But Joomla! is a much more advanced creature now. So why not use Joomla! itself? Show off the abilities of our favourite CMS. Yet another way that Joomla! can assist organisations and businesses.

Do you actually know of a Joomla! application where it is  used for documentation? If so, please tell me.

Before we think about the benefits of Joomla! it is worth spending a moment considering the manpower resources needed to create effective documentation. In my view these are the roles required

  • Editor – One or a few people in charge of final releases – these are language experts not Joomla! experts.
  • Technical auditors – One or a few people in charge of Joomla! accuracy
  • Web managers – A few people in charge of ACL controlling which author has access to which areas of the site
  • Web authors – Write the content – those with experience of the problems with support from experts
  • Recruiters – Monitor the forums to see who is solving problems and recruit them to document their experiences.

All will be volunteers. Perhaps they would feel more satisfied in their roles were their contributions acknowledged.

And, in my opinion, it would be better if those who had solved the problems were authors rather than the experts. They can speak the language of those who are meeting the problem. Experts will provide correct responses but sometimes couched in language the person meeting the problem for the first time does not understand.

The benefits of Joomla! for this area are, I am sure, already clear to you.

  • ACL – to control which authors have access to which section. Enforces a disciplined approach to providing the documentation.
  • Version control – allows roll back if needed
  • Templating – allows alternative presentation styles to be offered and compared.
  • Comments – see the previous post for how PHP manages user comments – a useful resource in their view.

Make it easier to translate

A new extension for Joomla! is Josetta. In some experiments with Josetta and a test version of what we would like to do it has proved very effective and very user friendly for the translators (3).

It allows the construction of a multi lingual web site with some specialised features.

  • Basic site in base language e.g. English
  • Isomorphic sites in other languages
  • Transfer from one language to another if the second language is available. Default to base language.
  • Progress measure for translation
  • Simultaneously manage several translations at once

All of which makes it very straightforward for the translators.

This will be demonstrated at JAB12. Come and tell us what you think.

 

 

Categories: Joomla Documentation | Leave a comment

Joomla! Documentation – What Others Do

Inventing new things is always difficult. Often better to build on the shoulders of others.

To consider designing a Joomla! documentation site from scratch is definitely not a good idea. Do you know an excellent documentation site? Easy to  use? Meeting the needs of advanced and beginner users? Available in more than one language? If you do, please tell us about it in the Comments below.

I thought to look at two sites you are probably familiar with.

MySQL

Here are some annotated screen shots from the Documentation for MySQL. The images are purposefully large (sorry) so that the text is legible. Click on the image to see it full size. Use the Back button to return.

Their documentation has a consistent pattern. Each page has relevant text and associated menus. Translation does not seem to figure although I am aware that the documents are available in several languages.

I like this organisation. What do you think? Let us know by Commenting.

MySQL 5.5 Reference Manual Home Page

MySQL 5.5 Reference Manual Home Page

And the next two images drill down into the documentation showing how they maintain their organisation.

MySQL 5.5 Reference Manual Chapter Head Page

MySQL 5.5 Reference Manual Chapter Head Page

 

MySQL 5.5 Reference Manual Chapter Level One Page

MySQL 5.5 Reference Manual Chapter Level One Page

MySQL 5.5 Reference Manual Chapter Bottom Level Page

MySQL 5.5 Reference Manual Chapter Bottom Level Page

Concern has been expressed that the Joomla! documentation will contain too many pages to allow for a sensible hierarchical organisation. In my opinion, the number of pages for MySQL is likely to be at least as great as for Joomla! and MySQL can be organised in a 4 deep hierarchy. What do you think? Is the Joomla! Documentation amenable to hierarchical organisation? How many levels deep would it be?

PHP

The documentation for PHP is very similar and these links are for similar images.

There are two major differences between the documentation for PHP and MySQL.

  • Language choice is always accessible. See the images above.
  • Every page allows for comments. ‘Wow!! What a moderation nightmare!’ I hear you cry. Indeed that is what happened to the PHP Documentation Team, Their solution? A very specific page of Do’s and Don’t's to filter out stray comments to more appropriate places in the PHP Site.
PHP Post A Comment

PHP Post A Comment

 Joomla!

You will have seen the Joomla! Documentation pages.  There are two main start points, one of which is rather dead, found here

What I want you to do

Especially if you are NOT coming to JAB12

If you could spare a moment of two I would really like you to post your view of how the Joomla! documentation should develop.

  • How can it better meet the needs of a range of users?
  • How can it be built so that it is easy to maintain?
  • How should we make it easy to translate?
  • Can we discover from the forums what the ‘hot’ topics or emerging ‘pain’ points are?
  •  Other suggestions for making it better and easy to manage?

Please use the comments below.

If you are coming to JAB12

First of all, please post your comments as described above.

Then come to the presentation Jon Neubauer and I are giving on Saturday, 19th May, at 1015 in Room 4.  We have some ideas, models and concepts to present to you and would love to receive your feedback.

Thank you for coming by

 

Categories: Joomla Documentation | Leave a comment

Joomla Documentation – A Proposal

This is a draft of the proposed site. It is for discussion. Please leave comments about any aspect of it.

The intention is to build a prototype web site for demonstration and discussion at JAB12 followed by a completed site by September 2012 to coincide witht he launch of Joomla 3.0.  If you could contribute please volunteer by email to addacumen AT gmail DOT com.

Build a Beginners Guide in 3 versions, across 3 languages
(versions for 1.7, 2.5 and 3.0, languages en, fr, de)

Green sections are the same for each version.
#*# indicates a section which will need different versions for ‘Beginner’; ‘Developer’, ‘Advanced’

  • What Is Joomla? A brief history. A brief description.
  • Why Use Joomla? Benefits of Joomla.
  • Who Should Use Joomla? A brief description of the range of users.
  • What Can Joomla be Used For? Applications scope.
  • How Joomla works.
  • Some Joomla Words – English words used with added meaning
  • Installing Joomla!
  • Upgrading Joomla!
  • Administrator Control Panel
  • Global Configuration
  • Users
    • User Manager #*#
    • ACL #*#
  • Managing Content
    • Categories
    • Articles
  • Menu Items
    • Menu Manager
    • Menu Items
  • Modules #*#
  • Plugins #*#
  • Extending Joomla!
    • Installing Extensions #*#
    • Components #*#
  • Diagnosing Your Problems #*#
  • Glossary
Categories: Joomla Documentation | Leave a comment

Learning Joomla

How to Write Helpful Joomla Documentation.

A Joomla Bike

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.
  • Searchable
  • 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.

Categories: Joomla Documentation | Leave a comment

Joomla 1.7 – R.I.P.

Joomla 1.7 will be unsupported from tomorrow (24 February 2012).

This is both good and bad news.

  • Good news - It is superceded by Joomla 2.5 which is a much more effective Content Management System(CMS)
  • Bad news - It requires site owners to upgrade their site if they want their site to remain secure.

The Managed Joomla service – run by addACUMEN, Intelligent Web Design – provides an effective content migration service which will transfer your site from earlier versions of Joomla to Joomla 2.5.

Categories: Joomla 1.5 | Leave a comment

Joomla 2.5

The new version of Joomla – Joomla 2.5 – takes over from tomorrow 24 February 2012 when Joomla 1.7 retires as unsupported.

Along with new features such as advanced search and automatic notification of Joomla core and extension updates, the Joomla CMS for the first time includes multi-database support.  You can now use Microsoft SQL Server if you want rather than MySQL.

The important features in Joomla 2.5 include:

  •  Automatic notification when a Joomla or extension update is available.  Site administrators will instantly have access to new notification buttons that allows them to see and act on the latest updates.
  • Natural language search engine to the Joomla core. Complete with auto-completion and stemming (for example if you type “running” in a search field you also see run), it is faster and more versatile than the standard search.

The addACUMEN service Managed Joomla provides easy access to these features and many others.

You can download Joomla 2.5 or Upgrade package from here: www.joomla.org/download.html.

Downloading and using the latest version of Joomla is the best way to ensure company and personal security needs are being met since it will have the most recent updates to protect against the latest security threats.

We appreciate that for some organisations this may be a burden too far.   An easy solution is to select options from Managed Joomla to meet your specific requirements.

Categories: Joomla 2.5 | Leave a comment