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.

I am always fascinated by the amount of Ajax tutorials and examples out there that totally ignore the backend part of an Ajax app. A lot of times you’ll find page-long ravings about the 6-7 lines of JavaScript that allow the client to make an HTTP request but when it comes to talking about the proxy script needed to allow for cross-domain requests a lot is glossed over as â��you don’t need to know this, just use this scriptâ��.

That would not really be an issue if the scripts offered weren’t that bad. Unsanitized URLs are the main attacking point for cross-server-scripting attacks. If you use a PHP_SELF as the action of your forms you shouldn’t be too confused about a lot of mail traffic from your server or text links on your site you didn’t sign off and get money for.

The other thing about Ajax information on the web that amazes me is that people keep complaining about the slowness and problems with converting data from one format to another on the client side. Let us not kid ourselves: even after all the articles, books and podcasts about Ajax we still have no clue whatsoever what a visitor uses to look at our products. We cannot tell for sure what browser is used, if there is assistive technology involved or anything about the specs of the computer the browser runs on. This to me makes the client side the least preferable place to do heavy calculation and conversion.

The server side, on the other hand, is in your control and you know what it can do. Complex regular expressions, XSLT conversion, all of this is much easier to do on the backend � and you know that the text encoding will work to boot. A lot of complexity of Ajax apps is based on bad architecture and design decisions and on relying on the client side to provide necessary functionality.

So if you ask me what the ratio of client-to-server code of a good Ajax app is I’d say 30% client and 70% server. The 70% on the server should be used to provide security, non-JavaScript fallback functionality (yay accessibility) and conversion of data to small, easy-to-digest chunks for the client (think HTML and JSON). The 30% client side code should mainly be used up to enhance the usability of the product and make it easier for your visitors to reach their goals.

So here’s my plan for 2008: whenever I talk Ajax I will try to cover as much backend as frontend. I’ll do this by partnering with other experts as I myself created some terrible PHP in the past. I hope that others will follow that example as Ajax is a wonderful opportunity to bridge the gap between frontend and backend engineering â�� and we have to talk to each other to create a good app.