I am spending far too much time keeping explanation tutorials of scripts in sync with changes in the code. This is why I wrote myself a PHP solution to do the work for me. I’ve found over the years that the best way to explain a script is to :

• Show an example
• Show the full source code
• Show the source code bit by bit followed by explanations what each part does

If you go and check Tutorialbuilder you’ll see that I managed to automate most of this with a PHP script. It does the following for you:

• It generates the tutorial parts from comments in the script source code.
• It converts the source code to displayable code (encoding it, adding line numbers, allowing for lines to be highlighted)
• It creates a downloadable version of the script with a correct file name
• It creates an executable version of the script without comments to link to with a script element.
• It can minify the script (remove all whitespace to cut down on file size)

In other words, it turns this source script into a tutorial like this using a template and some CSS (most taken from the YUI).

It is not a replacement for JSDoc but instead catered to be easier to use and explain the functionality of code rather than the syntax of the JS code itself.

Tutorialbuilder is licensed with BSD, so go nuts using it for yourself.

Last week I went to AKQA in London to give a brown-bag presentation on progressive enhancement. I took this chance to vent some of my ideas on the subject and counteract some of the criticisms I heard about the need for enhancing web solutions progressively.

I’ve come up with the following “Seven rules of progressive enhancement”:

1. Separate as much as possible
2. Build on things that work
3. Generate dependent markup
4. Test for everything before you apply it
5. Explore the environment
6. Load on demand
7. Modularize code

Instead of explaining them here, I’ve used a longer train ride to write up an article on the subject explaining the details of all the “rules” and examples of why and how to use them: Pragmatic Progressive Enhancement.

The article is licensed with creative commons, so you are very much invited to use and remix it to your needs.

I will upload my slides together with a video of the presentation once I got the material and checked if the video quality is good enough for publication.