Cincom® VisualWorks® Documentation: a Brief Overview and Glimpse Behind the Scenes

Each release of the VisualWorks IDE also includes “Release Notes” that cover both new and deprecated functionality. These notes are especially useful when porting your applications to a new version of VisualWorks. Given the frequency of the release cycle (approximately two per year), documentation typically appears first in the Release Notes and later in the PDF guides, though we endeavor for complete coverage whenever possible.

For each major component in the product (e.g., GUI, Database, COM, DLLCC, DotNet, Security, Web Application Server, Web Services, etc.) the primary documentation covers the component’s general architecture, functional organization and major APIs. The API documentation provides a more in-depth discussion than what is generally found in method and class comments. The PDF guides also note specific design issues facing application developers, offering bits of guidance and considerations for optimal performance. Whenever possible, the VisualWorks documentation provides real code examples to illustrate the product’s functionality. Application developers can often get started simply by copying this example code from the documentation and running it in a Workspace window. The documentation also provides overviews of some of the demo and example packages that accompany individual components.

Like all other parts of the product, the VisualWorks documentation undergoes continuous refinement. Each product release may include dozens of small changes, tracking new functionality, changes or deprecation of existing functionality, as Cincom engineers and publications staff coordinate the effort of tracking the evolution of the product. Each PDF Guide includes a part number and software release number on the copyright page, so that you can roughly establish its coverage of the product. Newer, more rapidly evolving subsystems receive more frequent PDF documentation updates, and all product changes receive coverage in the Release Notes.

Behind the scenes, VisualWorks documentation is now single sourced using the XML-based DITA content model. The integrated Help System also uses XML-based source documents, though in an older, pre-DITA format. We selected DITA over proprietary document formats such an MS-Word doc and more elaborate schemes such as DocBook, because it seemed to occupy the comfortable middle ground of an open standard that is comprehensive, extensible and yet not overly complex. As an XML-based format, it also opens the possibility of greater integration between the IDE tools and documentation content. Cincom uses the industry-standard Framemaker for maintaining the documentation and PDF for delivering it. While it has some limitations, PDF remains the simplest and most widely accepted system for delivering complex documents. For each major release, we also include a searchable index of the entire PDF document set.

To push beyond the limitations of PDF, we are currently exploring the possibility of supplementing PDF with an XHTML-based delivery scheme. In the future, we hope to further leverage both DITA and the VisualWorks IDE for a more integrated, flexible and powerful documentation system.