9.2.1. Make It Easier to Create Tutorials

Our first tutorials were incredibly tedious to create. Authors and editors wrote and edited the content in a tool such as Microsoft Word, then we started the publishing process. Our first step was typically to create a PDF version of the tutorial. High-quality printable versions of our tutorials are popular, and it's easy to create them from a single formatted document in Microsoft Word.

Once that was done, we would convert the tutorial document into a single HTML file. We would then take the file, break it into small pieces, and add the standard IBM header and footer to each small piece. This step gave us a number of HTML files (usually 50 to 100) that we needed to link together. In other words, if you look at the third panel in a section, clicking Next should take you to the fourth panel, and clicking Previous should take you to the second panel. We also needed to create a menu panel; from the menu panel, you can link directly to the first panel of any particular section. Finally, each panel had mouseover effects that had to be tested.

While the writer and editor worked on the actual content, our graphic designers created artwork for the titles of the sections and for the tutorial itself. It was important that the heading text look a particular way, so our designers created graphics that contained that text, drawn on the appropriate background. For some titles, both plain and highlighted versions were created for the mouseover effects.

Clearly, much of the tutorial-building process was hand-coded and error-prone (particularly when we were feverishly finishing a tutorial at 5:30 in the morning so it would be on the site by sunrise). We wanted to automate as many of these steps as we could, to save us time and minimize the chance of errors.

9.2.2. Show Our Audience That We Use the Technologies We Advocate

Another goal was to actually use the technologies we espouse. We were certainly aware of the irony of a site that promotes open, standards-based computing creating content with a closed-source, proprietary tool, such as Microsoft Word. One attraction of building tools from XML documents and XSLT stylesheets was that it enabled us to show the world that XML and XSLT can do useful work today. Choosing these technologies to manipulate structured data was a no-brainer for us.