Documentation: graphical representations difficult to interpret

[laurentlefort]

The document uses too many different style of figures for mainly two types of representations:

• The “UML-OWL” graphical style used in Fig. 1 (not sure which tool has been used to create this figure) is not referenced nor used elsewhere in the document
• The “property hierarchy” diagram used in Fig. 5 uses a different style to the one used in Fig. 9. Apart from the name starting by lower case letters, there is nothing in the diagram which mentions that this is a property hierarchy not a class hierarchy (there is a slight risk of confusion associated to the reuse of the symbol generally used for class inheritance in UML diagram)
• Figure 2 and 4 uses a recognisable linked data representation, Figure 6 uses almost the same one (rdf:type replaced by a, and no colours)
• Figure 7 (and Figure 8) uses a more compact one where the key relatiosnhips between the 3 and a half represented boxes (fi:ISSCAP_3, fi:ISSCAP_32, fi:ASFIS_COD and fi:ISSCAP_2005) are not explicitly marked up: lines without an arrow to mark the direction and not annotated with the name of the properties they represent (skos:inScheme, xkos:generalizes)
• And finally Figure 3.1 and 3.2 use a hybrid style (not quite an ontology representation nor a real example)

I recommend to be more consistent throughout the document with one style to show OWL content (for all diagrams except the property hierarchy one) and another one to illustrate RDF/Turtle content. For Figure 7, you should omit some of the content in the diagram (select only one of each annotation properties) but provide the corresponding Turtle content below in the same order as it is presented in the figure (or vice versa) to help the reader to match what’s in the figure to what’s in the Turtle example.

[tfrancart]

• We acknowledge that the different diagrams could be made more homogeneous
• We will improve this in the V2 of the document