Documentation modularity (structure)

XKOS is a bundle of SKOS extensions for requirements specific to the Statistical community which are not covered by SKOS alone and is aimed mainly at SKOS users:

handling of classification levels
mechanism to map two classifications together
sub-properties of the properties relating skos:Concept to one another refining the main thesaurus relationships.
plus a bunch of recommendations to use concepts from other vocabularies in specific places

The documentation is not structured in a way which helps the reader to progress from understanding the basic stuff (what to use when publishing a Statistical Classification, how to define levels, how to use the two main types of hierarchical relations) to the intermediate stuff (correspondence and concept associations, use of more specific “semantic” relationships) and then to the more advanced stuff of managing the evolution of classifications and of their correspondence tables (linksets) over time.

A reorganised documentation would be something like:

Introduction (with a mention of the intention to apply XKOS to publish correspondence table (linksets) in an approach aligned with what is used in the statistical community and aiming at solving issues associated to the evolution of classification over time)
Overview, with a figure showing the key classes and their relationships, the ones inherited from SKOS: Concept and ConceptScheme (and ClassificationLevel) and the new ones: Correspondence and ConceptAssociation with boxes introducing what will be discussed in the rest of the documentation (so same intent than current section 3 but different editorial choice in what to highlight/hide)
Next section on everything related to standalone classifications (5.1, 5.4, 5.4, 6., 8., plus the extensions to skos:broader/skos:narrower)
Next section on correspondence / mapping between classification (section 7)
Next section on advanced usage with a sub-part for the management of classification over time (5.2 and expanded content for the use of dcterms:valid described at the end of section 9) and possibly, a second sub-parts describing the semantic relationships defined as alternatives to skos:related. Specific examples should be located closer to the content they illustrate (e.g. 10.3 at the end of the correspondence section).
And a final section with a complete example and also references to “known implementations” (this last point further discussed in a separate issue).

linked-statistics / xkos

Documentation modularity (structure) #68