Title: Making Documentation Interactive and Customizable

Author: John Humphrys

Abstract: Take a Field Service Manual and put it in XML format. Transform this document into HTML and PDF (maybe) to show that one source document can generate the document into different output formats. Take a set of instructions in the manual, for example the instructions to configure a network switch, and make it interactive, such that, the user inputs the devices to be connected, and I return exactly how to configure the switch.

What: I will take a subset of one of our (Philips Medical Systems) Field Service Manuals and convert it to XML. I will develop my own DTD, or use DOCTYPE as its template. The design will be similar to project 3 using Tomcat as a web server. A client will connect to the server and the user will choose what he wants to view. For example, a field engineer most likely is familar with the manual, and only wants to see the various instructions peppered thoughout the manual without all the additional verbage. He will be able to select just one set of instructions or perhaps all the instructions.

Each set of instructions will contain a link to the next set of instructions in the manual. This is what field engineers want. They want to be able to navigate quickly through a manual to the information they want. They do not want to waste time paging through or constantly typing Ctrl-F.

The table of contents will be a list of links such that you can quickly navigate to the associated section. Likewise each entry in the table of contents will be a link taking you to the associated location in the manual. This will be most useful for the more casual user. 

Finally, it will have some interactive sections. Currently, our network has devices at various speeds and duplex settings. As a result, the field engineer writes this down and then figures out how to configure the switch. I will allow the engineer to select the devices that will be connected to the switch in a form. After this is submitted, in the server, I will determine how the switch should be configured and return it so that it can be printed out. 

Additionally, our manuals contain parts lists. These generally have errors and quickly become out of date as parts become unavalilable. Another major advantage of my approach is that the parts' list can be udated on the server and up-to-date lists made available almost instantly. The same is true for instructions that contain errors.

Why:  Currently our documentation is not very usable. It is 600-700 pages long which makes paper copies very cumbersome, and the PDF files are static (changes/corrections are only made yearly with major releases). The PDF files lack the quick and easy navigation that XHTML can provide.

As stated above, the ability to transform XML data on a server to XHTML format on a client, provides the ability to create special documents on the fly: like just the instructions or just the parts.

How: It will be very similar to project 3 where we used Tomcat and servlets. Much of my effort will be in defining the UI. Like project 3 that had a prefs page and a view page, this project will do the same. For example, the prefs page will let the user choose something like:

* Display full manual.
* Display only instructions
* Instructions to configure CISCO 1900 switch.
* Instructions to configure HP 2425 switch.
* Parts for HP VL420.
* Safety Requirements.

The view page will vary depending on what is displayed. For example, if the whole manual is displayed, I would design navigation on the left side of the page and content on the right.

The interactive section(s) will be developed using forms. 

Questions:  I am most concerned about setting up the initial environment to complete the project in a timely manner. You have always provided a startup environment for us. I would ask for some help and getting this intial setup solid before I begin my development.