Case study: integrating tutorial help with developer-written reference material
Arcos is a code-generation tool which is used to create database-driven web sites. It is produced by Kusala Web Developments (www.kusala.com).
Kusala needed documentation that would help web developers to use Arcos. Since the product is continually being enhanced, they also wanted to be able to modify and add to the help without recourse to a technical writer.
Background
Traditionally, web developers write the PHP source code from scratch. With Arcos, they build the site from existing PHP code, using XML to specify which PHP code components (fragments of pre-written PHP code) will be used. This methodology can greatly improve the efficiency of the development phase.
There is a set of pre-existing components, and new components are regularly being produced by Kusala. Typically, in a traditional authoring situation, software developers would produce notes on each of the functions, and then a technical writer would create reference material using those notes. Kusala wanted to avoid this for two reasons:
- It is wasteful of resource (a developer writes notes, and then a technical writer re-works the material).
- It means that there are at least two copies of the information in different documents. This can lead to inconsistencies.
What we did
The documentation is written in pure HTML, so that it can be used on both Unix and Windows platforms. We did not use any script or browser-specific enhancements.
The documentation is designed for web developers, and is highly technical. It is split into two main sections; tutorial and reference.
We focused our efforts on the detailed tutorial, which starts very gently, and leads developers through the major features of the tool. They can use the source code that we presented; they only need to change user names and passwords. This ensures that at each stage, they have a working model to use. If there are any problems, identification of the cause is a relatively straightforward process.
Much of the reference material already existed in various Word documents. We rationalised this and used it as the basis of many of the reference topics.
A subset of the reference section contains information about all the components that are available in the system. The source information is created by the Kusala development team using their development tools. It is contained within each of the components that they write. To extract the information, the development team use a script that generates HTML files — one for each component. The generated HTML help files do not contain any formatting information, but rather, they contain just a reference to a CSS style sheet. Therefore, the generated HTML help can be dropped into the main help system, and it automatically matches the look and feel of the other help topics.
Would you like to see what TechScribe did? Then download the HTML Help that we created.
Results
Arcos now has a help system that contains:
- Introductory tutorial information that will rarely change.
- Reference information that will rarely change.
- Reference information about the Arcos components. This can be modified rapidly by the software development team.
The software development team is not tied to using a technical writer to integrate their notes within the main body of the help system. Since there is no intermediate stage between the developers' notes and the users' help, there is no possibility that errors will be introduced into the technical reference for the components.
"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