As DTD and Schema objects are different, by nature, the documentation of a Schema cannot pretend to be a high-value documentation of the corresponding generated DTD. Nonetheless, we put emphasis on the preservation of elements.
 |
| ||||||
|---|---|---|---|---|---|---|---|
|
| ||||||
|---|---|---|---|---|---|---|---|
Everyone who works with a model needs this model being documented. As most technical documentation users may experience, one of the main problems they face is the reliability of the documentation, mainly expressed in terms of consistency and completeness against the model they documents. These qualities have to be maintained all along the life cycle of the model (DTD, XML schema...) depicted in the documentation. The goal of SchemaDoc is to help these people producing model documentations to fulfill theses consistency and completeness basic requirements. It's application domain is in the scope of XML modeling.
Therefore, users of SchemaDoc are those who are involved in de production and/or documentation of an exchange model. XML model designers will be provided with a documentation environment that makes it possible to create and maintain model documentation while they maintain the model itself. Technical writers who have to document an application model will find in SchemaDoc a documenting model as well as a tool that help's them to improve and check the quality of the documents they produce.
Not every one who uses the model will be interested in SchemaDoc. For instance, writers who have to produce documents or parts of documents conforming to the model may ignore SchemaDoc as well as they ignore which technologies and which modeling process has been used to design the model they use. In many cases they won't even have knowledge of the model documented with SchemaDoc.
While documenting a model, different strategy are possible:
Externalizing the documentation
The most obvious way to document a model is to separate the documentation from the model. For instance, the documentation will be stored and structured in a set of Open Office files while the model will be stored and structured as an XML Schema document. These two documents are edited in parallel, that is to say that they are not tied to each other.
Consistency is then checked through a pure intellectual process.
Self-documenting and including the documentation inside the model
As soon as the model exists in a concrete formalized form (XML schema files, for instance), it is tempting to enrich this form with documenting information. At a very basic level, this need has been forecasted by the designers of the formalized language who allow the inclusion of comments, that is free text which escapes the formalism. A more elaborated use of comments is to formalize their content so that they can be processed by programs. Javadoc is a widespread example of this strategy.
The next step is to extend the formalism itself so that the
objects represented in this formalism can be self-documented. XML
Schema enables this strategy trough the xs:annotation element.
This strategy is suitable to all reference manual documentation, where object definition is the principal objective of the reader. As soon as users guide needs to be wrote, oriented to functional and use-case information sets more than objects, this orientation is no more suitable.
Self-defining by including the model inside the documentation
Emphasizing the documentation role may lead to consider that the expression of the model in a formalized language (DTD, XML Schema, etc.) can be a by-product. This is the case where the documentation "self-defines" the model. To be effective, this strategy assumes that the documentation formalism is expressive enough to embrace both documentation and formal definition purposes. There is no need to invent form scratch the documenting model nor the formalizing language subset. Both can be derived from existing formalisms.
If this idea seem to be attractive, the attraction needs to be minored by the fact that no tools (word processors) enable this working method. In plus, this method no more works as soon as the model is to be documented for different purposes, having different audiences. In this case, it becomes difficult to reuse the same object definition in two different documentations.
Summary
Designing and producing the documentation as an independent document opens choice to an unlimited range of formalisms, editing and publishing environments. This freedom has a cost : the independence of the documentation makes consistency between documentation and the model a pure intellectual and abstract process.
Self-documenting formalized information (models, code) is a very attractive solution. It secures the unity of the documentation and the documented content. By itself, this technique does not warrant that consistency will derive from unity. Moreover, though proximity between documentation and documented content helps in some kind of intellectual consistency assessment, it's useless when documentation refers to pieces of information spread around the model. As far as expressing the relationships between components is a major challenge of documentation, linear proximity is a rough approximation of connexity. At the same time, the physical unity of model and documentation come at the risk of unintended alteration of the model while editing the documentation (and vice versa). In the case of XML Schema and related technologies (editors, parsers, data representations, etc.), the occurrence of documentation elements may lead to discordant treatments depending on the processing environment. Even worse, the DTD formalism does not integrate any structured element that is intended to receive documentation.
Self-defining inherits the benefits of parallelism without it's major inconvenience. In return, before writing the first word of the documentation or the first element of the model, it is necessary to produce a model of content that will host all the necessary information. Though the charge may seem heavy, it has to be asserted that deep self-documentation may lead to a complex formalization and processing of the included documenting structured components. This strategy has been explored at the early stages of SchemaDoc. It's main and disqualifying drawback was due to practical considerations. In cases where the documentation may extend over large, complex and numerous sections, manipulating the whole documentation to gain access to the model overhauled the operational capabilities of many tools.
One way to overcome some of the limits of these strategies is to consider that they provide a "material" basis on which some logical framework can be tailored. This framework will then support it's own semantics and be supplied with appropriate tools. Expressiveness of the formalism and consistency between documentation and documented information depends completely on the framework, no matter which bias material base may induce. This is the choice we have made in SchemaDoc.
In SchemaDoc, the model exists by itself, outside the documentation, through its facets, such as a collection of XML Schema files. The documentation is edited as an XML document that practically exists by itself but that explicitly refers to elements defined in the model. How far is this documentation consistent and complete will be checked by a dedicated SchemaDoc processor. During the process, references to the model are resolved, the information collected from the model definition is expanded inside the documentation. Therefore, the processed documentation contains any formalized definitions that are considered relevant, from the documenting perspective.
Thus, SchemaDoc seems to extend the capabilities of self-defining strategy, by passing its limitations. But SchemaDoc does not turn the back the self-documentation contribution. First, the content of the documenting elements provided in the model definition are included as part of the documentation. Secondly, this content can use the documenting formalism of SchemaDoc in such a way that "inline" and "outline" documentation interact with each other.
A processed SchemaDoc documentation contains a structured merge of all the information available in the SchemaDoc source XML document, the documenting information contained in the model definition, the model definition and many extra value-added information (graphics, cross-references) that can be extracted through the process of the native information.
In SchemaDoc, we came to the agreement that documenting a model was a specialization of a technical documentation task. We kept in mind that documentation/model consistency and adjustable completeness of the documentation regarding the model were the main areas of concern.
The goal of the SchemaDoc project is to provide XML model designers with a documentation environment that makes it possible to create and maintain model documentation while they maintain the model itself.
To reach a wide a readership as possible, SchemaDoc is designed to provide different output formats, such as HTML or print, from a single source.
SchemaDoc uses a merge of the DocBook model with the schema of XML Schema. The glue between these two models is made using specific objects of the SchemaDoc namespace.
Also, the environment is similar to Javadoc in the way that it extracts documentation information from the model itself. It differs from Javadoc in the sense that it is possible to write comprehensive and instructive documentation based on links to the model.
The SchemaDoc present solution is designed to document models described in the XML Schema formalism. At first sight, users who's applications require DTD descriptions can not use SchemaDoc. It is not the case. These users are encouraged to distinguish between a referential model definition and operational translations of their model. The former can be expressed in the XML Schema formalism while the latter can be expressed in the DTD formalism. SchemaDoc takes this need into account and provides a Schema to DTD translator. This translation tries to be smart enough to preserve the documentation of the elements of the generated DTD.
As DTD and Schema objects are different, by nature, the documentation of a Schema cannot pretend to be a high-value documentation of the corresponding generated DTD. Nonetheless, we put emphasis on the preservation of elements.
Much has still to be done to ensure that it is preservation works, event at the element level.
In the long term, SchemaDoc aims at documenting XML models. It is intended to be extensible to natively document DTD as well as any kind of models based on an XML language, for example RelaxNG.
The term "SchemaDoc" is used to describe three kinds of real world objects : a project, a format and a publishing tool.
As a project, SchemaDoc tends to accomplish the goals it's been assigned to. There's no functional upper limit to what is provided as the project : development facilities and tools, mailing lists. The lower limit is the availability, by all means, of the format and the source code of a tool.
As a format, SchemaDoc is an implementation of a documentation model. It is provided as a documented XML Schema, the documenting part being recursively implemented in SchemaDoc format itself.
As a tool, SchemaDoc is aimed at publishing SchemaDoc documents, not writing them, not even editing their textual components. It comes as :
a set of Java packages and XML files developed by the SchemaDoc project,
the SchemaDoc format,
and a collection of freely available XML files (DTD, stylesheet, etc.) provided for compatibility and convenience purpose.
Besides these three acceptations which define the core of SchemaDoc, the deliverable SchemaDoc package may also come with a non mandatory and unnumbered set of SchemaDoc goodies (such as XML editors configuration files). Though some of these goodies may be documented here, they should not be considered as parts of SchemaDoc. Think of them as being tricks, shared between SchemaDoc users.
This documentation is meant to be red by end users and developers. The first sections will apply to every persons who is interested in SchemaDoc purpose, concepts and so on. Next sections will mostly be red by people who want to use SchemaDoc, either end users or local gurus. Last sections cover topics that might concern developers.
These readers classes are not disjunctive. One may be interested in SchemaDoc and want to have a closer look at how it really works. A user may want to customize the way SchemaDoc produces HTML output.
Users
Users will range from end users to local gurus. Though all would benefit from the reading of these pages, this documentation is mainly intended for people who prescribe, adapt or install documenting environments.
Developers
There are many reasons why someone would like to modify the behavior of the SchemaDoc tools. Some just want to customize a chunk of XSL style sheet while others will want to enhance the features provided by SchemaDoc.
Technical writers who want to improve SchemaDoc documentation will also need to have a variable understanding of SchemaDoc insights, depending on which part they are documenting. SchemaDoc being documented with SchemaDoc, they will also need to know how to use it and/or install it whether some other people can install it for them or not.
The project began as internal engineering at Tirème SARL (with Pierre Attar) making it possible to maintain a large technical DTD documentation set for customers. The original project used SGML technologies.
With the arrival of XML and Schema, the project switched to these environment with the assistance of Chadocs (Bruno Chatel) in defining how to convert from Schema to DTD.
For both, the current objective is to provide SchemaDoc as an open source environment once the core functional basis has been fully industrialized.
 |  |  |
| SchemaDoc documentation | 2. Installing SchemaDoc environment |