MS Concept

  • prefix: msc:
  • schema: b:




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


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.


The approach you take is expressed in the shadow element of b:has. The XML fragments below are included in the msc:Role/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 -->
  <b:has b:ref="Docs" b:type="ms:Type/Collection" b:is="ms:Role/Documentation">
    <b:shadow b:map="unit.id" />      <!-- not needed: default -->

  <!-- second approach, per language -->
  <b:has b:ref="Docs" b:type="ms:Type/Collection" b:is="ms:Role/Documentation">
    <b:shadow b:map="client.lang" />

  <!-- All docs in a local unit -->
  <b:has b:ref="Docs" b:type="msc:Type/Manual"
     b:is="ms:Role/Documentation" />

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

Also, remember that b:has carries optional attributes when and unless, so you are able to have ways to document groups of Units in different ways.

Schema components


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

mark@overmeer.net      Web-pages generated on 2023-04-13