This part of the tutorial explains how to design a human readable documentation. When browsing an ontology, it is very important to provide accurate definitions and examples of how to use it. If these are not provided, the ontology will be very difficult to reuse. Having a documentation easy to navigate, which explains every concept and relationship separately and which presents an overview and examples improves the understandability of the whole ontology to other people.
Some people address this step by pointing to a report/deliverable/paper where the ontology is described. Although this helps, it is not easy to navigate and will drive crazy any final user. I don’t recommend it. Furthermore, according to my experience, if the ontology is documented in a paper then the information will be of little use.
Making a proper documentation is difficult and takes time. Fortunately, there are some tools to help you overcome this task, like LODE, Parrot, OWLDoc, neologism, Ontospec, etc. I have worked with LODE, Parrot and OWLDoc, so I will only cover these here:
- LODE: For me it’s the best of the tools I’ve tried. It is a web service that takes as input an owl file and generates an html. The html is W3C-style with the definition of each of the terms extracted from the domain, ranges and metadata of your owl file. If you extract the appropriate bits you can automatically create templates to customize your documentation with additional images, explanations and examples (like this one).
- Parrot: Very similar to LODE, although the styles used are different and you have to clean some of the properties not defined within the namespace of your ontology (like the ones used to add metadata). It works really well, and my choice picking LODE instead of Parrot is a matter of styles.
- OWLDoc: NeOn Toolkit plug-in that generates an owl documentation javadoc style from your .owl file. I don’t personally like it much, as customizing it is a bit of a pain.
Once you have your html template from one of these tools (with all the concepts of the ontology fully covered), you should add sections describing an overview of the model and examples. My suggestion is to follow the structure of W3C documents, namely:
- Title and date of the release.
- Metadata: Authors, contributors, version, imported ontologies, license, link to previous version, link to the latest version.
- Abstract: small summary of your ontology in 2 lines. I recommend pointing to the owl file here as well.
- Table of contents of your html document.
- Introduction: provide context to the ontology. What are its goals and the benefits of using it?.
- Namespace declarations: Namespace URIs of all the vocabularies used within the document (this could be found at the end as well).
- Overview of classes and properties: Very small section with the list of tables and properties of the ontology, for making the navigation easier to the reader.
- Description: Diagram of the ontology concepts, relationships and how they are related to each other. Usage examples might help clarifying things as well.
- Cross reference section: this is the section automatically generated by the tools covered above. Just copy what they generated J
- Acknowledgements, specially remember to include the developers of the tools you have used.
Want to see some examples? Check PROV (W3C), some commonly used vocabularies like foaf or Dublin Core (which cover the points listed above with their own structure) or some of the ontologies I’ve been publishing, like p-plan or wf-motifs. Note that the order in which the points of the list appear is not mandatory. Modify it in order to make your ontology easier to use to the final user!
This is part of a tutorial divided in 7 parts:
- Overview of the tutorial.
- (Reqs addressed A1(partially), A2, A3, A4, P1) Publishing your vocabulary at a stable URI using RDFS/OWL.
- (Reqs addressed P2, P3). How to design a human readable documentation. (this post)
- Extra: A tool for creating html readable documentation
- (Reqs addressed P4). Derreferencing your vocabulary.
- (Reqs addressed A1 (partially)). Dealing with the license. (To appear)
- (Reqs addressed A5, P5). Reusing other vocabularies. (To appear)