Friday, 8 April 2011

Is the Moodle project dead?

While you may have heard the design mantra "Content is King", perhaps you might not be familiar with the development mantra that "Documentation is King".

In June 2010 I developed a Block for Moodle to connect Moodle to another piece of software.  This block was developed for version 1.9, using the documentation based on the instructions provided in http://docs.moodle.org/en/Development:Blocks.  Although the instructions were sparse I managed to create a working Block.

A few months later I tested it against the latest release version 1.9.8.  It was all still working.  Shortly after this a customer asked if it worked on version 2.0.  Unfortunately when I tested in version 2 my module did not show up.

Assuming that they had not changed too much I started looking through the documentation.  I was stuck for a little while with the version.php section as I initially assumed I should be entering

$this->version = 2004111200;

This through me for a while because this will actually kill Moodle completely with no error messages...  The correct value is

$plugin->version = 2004111200;

Which is about as obvious as any undocumented code.

Shortly after my break through in this section there is the wonderful section

TODO: New settings.php method

Well what a great help.  It appears this method has been in Moodle since 2009, but as of April 2011 no one has seen fit to mention it, despite it replacing config_global.html.  I am not aware of a successful project of this nature that does not have a complete tutorial on how to create a simple add-on.  

It is the most frustrating thing to do for any developer, break backwards compatibility and not provide the appropriate documentation on the requirements to make your code compatible.  While those who make a direct living from your product might have the time and the resource to scourer through source code those on the fringes that are also adding significant value to your product do not.  

Documentation is King, programming languages and software grow when it is in abundence and suffer when there is a shortage.  Lack of documentation over 2 years after you introduce a new method and 5 months after you release the product is essentially unacceptable, and the sort of thing that will kill off use of your project.

No comments: