Browse Prior Art Database

Documentation Generator for External Resources

IP.com Disclosure Number: IPCOM000020991D
Original Publication Date: 2003-Dec-16
Included in the Prior Art Database: 2003-Dec-16
Document File: 3 page(s) / 45K

Publishing Venue

IBM

Abstract

This article defines a software mechanism to automate the process of generating documentation for software resources. Without this mechanism, document owners face the common and known maintenance issues that are related to keeping project documentation on the software resources being used up to date.

This text was extracted from a PDF file.
At least one non-text object (such as an image or picture) has been suppressed.
This is the abbreviated version, containing approximately 44% of the total text.

Page 1 of 3

Documentation Generator for External Resources

When writing technical documentation for a software application, designers, developers, and technical writers (i.e., document owners) often find themselves in the never ending situation of keeping the project's documentation up to date. Certain sections of a project's documentation are more difficult to keep up to date than others. This is very true for sections that detail the configuration and structure of software resources that are used in the application. Since applications executing in today's software environments need to interact with multiple resources in order to accomplish a specific task, it is very common to find these types of sections in a project's documentation. For instance, if an application program connects to a database to read and write enterprise information and connects to a messaging system to receive and send messages, then a well-thought design document will include detailed information about the different schemas, tables, triggers, and views that were created in the database as well as the queue managers, inbound and outbound queues that were defined within the messaging system. Technical writers and developers keep this information up to date by manually querying the resources and updating the project's documentation by hand. This can be a painful process especially when changes are performed frequently against the software resources. For instance, if tables are added, deleted, or altered
(e.g., columns are added) then document owners must make sure that all these changes are reflected in the project's documentation.

Proprietary or standardized software APIs (Application Program Interfaces) are used for querying the external software resources (e.g., databases, message oriented middleware systems, and rules engines). These APIs provide the set of instructions that need to be invoked to dynamically find out which are the different elements or components that were defined within the external resource. The mechanism described in this article requires any resource that participates in the automation process for generating documentation to have a corresponding API that can be used to query the resource in order to explore the different components defined within that resource.

By automating the process of generating documentation for external software resources, designers and developers can focus on important project issues such as the design and implementation of the software application instead of spending time manually updating the documentation of the external software resources used by the application.

As described earlier, the preferred embodiment of the mechanism requires and uses a set of software APIs. The following steps should be followed by the software implementation of this mechanism:

Identification of the resources and APIs to use.

Query the resources with their respective APIs to find out which components are

defined within the resources. Generat...