Case study: integrating tutorial help with developer-written reference documentation
Arcos is a code-generation tool that is used to create database-driven websites. It is produced 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 existing 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.
There is a set of existing components, and new components are regularly produced by Kusala. In a typical technical writing situation, software developers produce 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 operating systems. We did not use script or browser-specific enhancements.
The documentation is for website developers, and is very technical. It is divided into a tutorial and a reference section.
We put our effort on the detailed 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 there are problems, identification of the cause is a simple process.
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 generates one HTML file for each component. The generated HTML help files do not contain formatting information, but instead, they contain a reference to a CSS style sheet. Therefore, the generated 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 now has a help system that contains the following 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 possibility for 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.
RSS feed