Scenario:
Automation of the Program Help Creation Process

Any software developing company faces the task of creating Help for programs. Moreover, as a rule, this documentation exists as several versions: User Help, Web version and the documentation for internal corporative use. We had to face this problem too, and the scenario below presents a reliable and tested solution.

I. Problem Statement.

The problem is creating SDK documentation. The analyses shows that all the information, contained in the documentation, can be logically subdivided into three types: the description of namespaces, the description of classes and interfaces, articles. Therefore we developed schemas for the three document types.

II. Preparing the Documentation Source Texts.

• While creating classes and interfaces, the developers write their descriptions in the comments.
• Parallel to this, namespaces descriptions based on standard XML schemas are created.

III. Literary Revision

• A special script extracts the descriptions of classes, interfaces and namespaces from the program code and forms a set of XML-documents of them, which is later passed over to a technical writer.
• The technical writer revises the material submitted, adds and restructures the information, if necessary, in such a way so that the documentation should be clear to an unskilled reader.

IV. Publishing

• The literary revised descriptions of classes and interfaces are saved in the program's text and replace the source comments. Now any team member can easily understand the program code, written by his colleagues.
• The draft documentation is saved in the XML format for further revision.
• Through the menu File-->Publish-->Save as HTML, an XML document is saved as a set of ready-to-use HTML-files, all you need to do now is upload them to the web-server.
• Through the menu File-->Publish-->Save as chm, we get a compiled Help-system, which can be provided with the program.

If you ever need to change the documentation, you won't have to do it with three separate documents - mere changing the source XML-file will suffice.