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”:http://icant.co.uk/sandbox/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”:http://icant.co.uk/sandbox/tutorialbuilder/democode.js into “a tutorial like this”:http://icant.co.uk/sandbox/tutorialbuilder/example.php using a template and some CSS (most taken from the “YUI”:http://developer.yahoo.com/yui).

It is not a replacement for “JSDoc”:http://jsdoc.sourceforge.net/ but instead catered to be easier to use and explain the functionality of code rather than the syntax of the JS code itself.

“Tutorialbuilder”:http://icant.co.uk/sandbox/tutorialbuilder/ is licensed with BSD, so go nuts using it for yourself.

[tags]code,tutorials,helpers,documentation,javascript,php[/tags]