The previous incarnation of the ontology documentation had a number of nice features that are no longer present in the bikeshed implementation. There are also a few improvements and additional features that I can think of. The following is a list of desired features, some of which were already present in the previous version of this tooling, and have proven useful to me when using the ontology documentation:
-
It would be useful to distinguish between explicitly asserted and inferred items. This would explain what is "inherited", and what is unique to the particular element. E.g., asserted superclasses and inferred superclasses, inferred datatype properties and asserted data type properties, inferred object properties and asserted object properties.
-
It would be useful to display forward properties for each component that have the component in the domain. Simply displaying the reified relationships that have the particular element in their domain is not as useful to me.
-
It would be useful to mark whether a relationship (and / or associated forward property) is transitive, functional, inverse functional, etc. Also, it would be useful to display the multiplicity for each source and target (e.g., component - performs -> function: a component can perform many functions, but a function can only be performed by one)
-
It would be great to have a diagram showing the immediately related elements. E.g., all superclasses and subclasses, attributes, and relations to other elements. In the previous documentation, this was done using class diagram syntax. Possibly differentiate between class definition and class usage diagrams to show different aspects.
-
Inference rules and / or validation rules / constraints specific to the particular ontology should be displayed.
-
Useful would also be some (at least) atomic, common usage examples. Sometimes I found myself jumping through the ontology documentation, noting down relationships of interest on a piece of paper, in an effort to try and determine how to represent a particular piece of information (e.g., supplier-client pattern, component-function pattern, etc.).
-
SysML embedding is missing.
-
I see a version of the ontology at the top - this is a great addition. It would be useful to also include the version of the imported ontologies.
-
It would be great if a PDF could be created from the entire documentation - it is unclear to me if this is supported.
Some additional feedback:
-
Instead of listing external concepts, aspects and reified relationships from other ontologies, is it possible to simply link to the relevant bikeshed document? Otherwise this significantly increases the size of the document, and leads to potential synchronization errors.
-
"Terms defined by Reference" seems to have a bug, where the content is not displayed properly. It is unclear whether this section is needed, since external terms could be linked to.
The previous incarnation of the ontology documentation had a number of nice features that are no longer present in the bikeshed implementation. There are also a few improvements and additional features that I can think of. The following is a list of desired features, some of which were already present in the previous version of this tooling, and have proven useful to me when using the ontology documentation:
It would be useful to distinguish between explicitly asserted and inferred items. This would explain what is "inherited", and what is unique to the particular element. E.g., asserted superclasses and inferred superclasses, inferred datatype properties and asserted data type properties, inferred object properties and asserted object properties.
It would be useful to display forward properties for each component that have the component in the domain. Simply displaying the reified relationships that have the particular element in their domain is not as useful to me.
It would be useful to mark whether a relationship (and / or associated forward property) is transitive, functional, inverse functional, etc. Also, it would be useful to display the multiplicity for each source and target (e.g., component - performs -> function: a component can perform many functions, but a function can only be performed by one)
It would be great to have a diagram showing the immediately related elements. E.g., all superclasses and subclasses, attributes, and relations to other elements. In the previous documentation, this was done using class diagram syntax. Possibly differentiate between class definition and class usage diagrams to show different aspects.
Inference rules and / or validation rules / constraints specific to the particular ontology should be displayed.
Useful would also be some (at least) atomic, common usage examples. Sometimes I found myself jumping through the ontology documentation, noting down relationships of interest on a piece of paper, in an effort to try and determine how to represent a particular piece of information (e.g., supplier-client pattern, component-function pattern, etc.).
SysML embedding is missing.
I see a version of the ontology at the top - this is a great addition. It would be useful to also include the version of the imported ontologies.
It would be great if a PDF could be created from the entire documentation - it is unclear to me if this is supported.
Some additional feedback:
Instead of listing external concepts, aspects and reified relationships from other ontologies, is it possible to simply link to the relevant bikeshed document? Otherwise this significantly increases the size of the document, and leads to potential synchronization errors.
"Terms defined by Reference" seems to have a bug, where the content is not displayed properly. It is unclear whether this section is needed, since external terms could be linked to.