Case study: integrating tutorial help with developer-written reference documentation

Arcos is a code-generation tool that is used to create database-driven websites. Arcos is developed by Kusala Web Developments.

Kusala needed documentation that helps website developers to use Arcos. Because the product is continuously improved, Kusala wanted to be able to change the help without using a technical writer.

Background

Usually, website developers write the PHP source code from scratch. With Arcos, website developers create a website from PHP code components. The website developers use XML to specify which PHP components will be used. This method increases the efficiency of the development stage.

A set of components is available. New components are regularly developed by Kusala. In a typical technical writing project, software developers write notes about each of the functions, and then a technical writer creates reference documentation from those notes. Kusala did not want this method for two reasons:

The method wastes resources. (A software developer writes notes, and then a technical writer changes the notes to create reference documentation.)
The same information is in two different documents. This repetition can cause inconsistencies.

What TechScribe did

The documentation is written in HTML. Therefore, it can be used on both UNIX and Windows. We did not use script or browser-specific enhancements.

The documentation is for website developers, and is very technical. The documentation is divided into a tutorial and a reference section.

We put our effort on the tutorial, which starts simply and shows website developers the primary features of the software. Website developers can use the source code that is in the tutorial. The website developers need only to change user names and passwords. This method makes sure that at each step, the website developers have a working model to use. If problems occur, identification of the cause is simple.

Much of the reference documentation existed in different Word documents. We made the information clear, and then used the information as the basis of many of the reference topics.

Part of the reference section contains information about all the components that are in the system. The source information is created by the Kusala development team using their development tools. The source information is contained in each of the components. To automatically copy the information the help files, the development team use a script that creates one HTML file for each component. The HTML help files do not contain formatting information, but instead, they contain a reference to a Cascading Style Sheet (CSS). Therefore, the HTML help can be put into the help system, and the appearance is the same as the other help topics.

To see what TechScribe did, download the HTML Help.

Results

Arcos has a help system that contains this information:

Introductory tutorial information that will rarely change.
Reference information that will rarely change.
Reference information about the Arcos components. This information can be changed quickly by the software development team.

The software development team does not need a technical writer to merge their notes into the help system. Because the software developers' notes are automatically put into the help system, the risk of errors is decreased.

"Although this was a very technical product Mike quickly got to grips with it and the quality of the documentation provided was first class."

Richard Wakefield, Managing Director, Kusala Web Developments.