Home

• explain
• command-line
• schemas
  • b: ms: base
  • c: msc: concept
• contact

MS Concept

• prefix: msc:
• schema: b:

Categories:

• constants
• documentation
• identities
• stores

documentation:

• c:manual

Category: documentation

Documentation can (should) be large, and is a serious challenge for many projects. The way how to organize documentation has much to do with personal and organization preferences. Therefore, th

Organization

Two different grouping approaches are useful:

Group per unit;

In this case, all documentation and its translations of a single Unit are in a single documentation Unit (usually with the same name);

Group per language;

Now, each language is a separate Unit, where the Unit names are used as index.

The first solution is simplest when a new original Unit is added: any release of data will result in a release of its documentation. The second solution is the easiest for translations: different people need to update translation tables for different languages.

In the second approach, clients load all documentation of the language they understand. Even for Units they are not interested in. The first approach load all languages for the Units they need. Both approaches have advantages and disadvantages.

Various intermediate approaches can be designed. For instance, the original language in the uploaded module, and only translations in separate Units in some other Collection. Maybe only the cheapest documentation records in the Unit, and the larger blocks in the external Units?

It is RECOMMENDED to design a consistent structure for the documentation within one Namespace, but that is not required: the clients will search between available documentation for the best fitting selection.

Examples

The approach you take is expressed in the shadow element of b:has. The XML fragments below are included in the ms:Type/Rules Unit which describes certain collection. The documentation is in a sub-colection named "Docs". The default shadow mapping is unit.id.

  <!-- first approach: one on one -->
  <has unitref="Docs" role="ms:Role/Documentation">
    <shadow map="unit.id" />      <!-- not needed: default -->
  </has>

  <!-- second approach, per language -->
  <has unitref="Docs" role="ms:Role/Documentation">
    <shadow map="client.lang" />
  </has>

  <!-- All docs in a local unit -->
  <has unitref="Docs" type="msc:Type/Manual" />

  <!-- Each unit has docs is a separate Unit in same archive -->
  <has type="msc:Type/Manual" role="ms:Role/Documentation">
     <shadow map:="unit.id ~ '.doc'" />
  </has>

Schema components

c:manual

The payload of a Unit which is specialized in documentation texts.