Tesmond's Useful Design

I cannot tell you how many programming books I have read which drill in the importance of documentation.  Of course documentation is not always perfect, but I genuinely thought that every programmer realised it was vital to the health of a project that the documentation is as good as possible. Reading this sentence though suggests the Moodle development team have been reading a different set of books to me:- Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here.  Moodle.org It is perhaps stranger still to me that the most important set of documentation the How to create a Moodle Block is still not up to date with the current version!  Luckily is you spend enough time looking around in the PHP code you can find the information you want, but this should ...

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 beca...