 |
| ||||||
|---|---|---|---|---|---|---|---|
SchemaDoc provides XML model designers with a documentation framework that enables to create and maintain model documentation while they work on the model itself. The model is created as a set of XML Schema and the documentation is a single book or set of HTML files linked to the model and using its definitions.
As a framework, the scope of a SchemaDoc project is to manage the documentation of information models described as XML models. The intent is to be able to manage all reference and user's guide documentation of the model itself. In this sense, people that will read SchemaDoc documentation are people creating engineering around the model. SchemaDoc will not meet all the requirements of end users of the model, as they need documentation on the user's interface developed to manipulate the model rather than on the model itself.
SchemaDoc is a framework, a model, a publishing tool, and a project. This document applies to all these aspects of SchemaDoc. Therefore, people who would like to edit this SchemaDoc document (designers, programmers, documentation writers, users, etc.) will face the same limitations as those experienced by end users working on their own information models. SchemaDoc as a framework, does not intent to provide a editing environment to SchemaDoc as a project.
SchemaDoc documentation is book-oriented, allowing a model designer to write documentation describing a model. As all is related to technical documentation of the model, this book can include specific sections.
SchemaDoc uses a merge of the DocBook model with the schema of XML Schema. The glue between these two models is realized using specific objects of the SchemaDoc namespaces.
An alternate solution could be to put documentation objects within the schema. This solution has not been used because all tools at this stage assume a complete conformance to the schema model, and because, when it is necessary to have a large set of documentation, the documentation elements of the schema model are not sufficient.
In the documentation produced by SchemaDoc, it is possible to define a hierarchical structure and paragraphs in order to write efficiently. Specific documentation objects of specific parts of the model are identified. This enables transversal reading of the documentation; this also makes it possible to use this information in specific IDE environments.
Regarding to the model, features provided are :
Schema specific xs:appinfo structure to display the model using titles, sections, and specific formatting;
links between redactional parts of the documentation and the model. This enables quality checks on the documentation in order to be sure that all quoted objects exist; this also enables hyperlinking mechanisms;
specific objects documentation in the redactional parts enabling to fully isolate objects documentation for reuse purpose.
For formatting documentation, the following features are available:
HTML, PDF, and DocBook formatting. The last one is used if is a need to provide a documentation that needs to be modified outside of the SchemaDoc environment;
Quality checking tools to validate conformance of the documentation with XML Schema objects;
DTD generation from the schema information model (not yet implemented) ;
In the HTML generation, tools provide hyperlinking facilities (in the code and in the documentation), direct access to objects, tables of contents.
To use this environment, you need first to create some documentation (see "Section 5, “Creating documentation for a new model”") and then use the tools to generating outputs (see "Section 6.2, “Output generation tool installation”").
SchemaDoc version 2 provides a first implementation of an intelligent converter to generate value-added DTDs from all schemas managed by SchemaDoc.
The tool is documented (see Section 8, “XS2DTD documentation use”) and its specification is provided for information
 |  |  |
| 3. The environment | 5. Creating documentation for a new model |
