Generating tutorials from source comments with Tutorialbuilder

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.

Tags: code, documentation, helpers, javascript, php, tutorials