Screenshot
Permanent URL: http://purl.obolibrary.org/obo/uberon/references/reference_0000000
Status: intermediate draft
Authors and contributors:
Date: 2012
Document Type: metadata_description
This article describes the inline documentation system used by Uberon. The article is itself a component of the system.
Documentation is essential for ontology development. yet there is no standard way to document an ontology. In addition, there is a tendency for external documentation (wiki pages, web pages, etc) to drift from the ontology.
This ontology aims to be as self-documenting as possible. In addition to the standard metadata associated with each class, we embed articles in the ontology. These articles may describe abstract design patterns or templates that are repeated throughout the ontology, or the modeling of a particular piece of biology (e.g. the heart). Some articles are of interest to users of the ontology, as they describe in more detail the system being represented and why it was represented in a particular way. Other articles may be solely for the developers of the ontology.
Each article is represented as an individual, and gets a unique URI. For example, the URI for this article is http://purl.obolibrary.org/obo/uberon/references/reference_0000000.
Each article is then adorned with metadata, using properties from vocabularies such as dublin core. The text of the article is represented using dc:description with a string value. The text is authored using a variant of markdown syntax, which can then be translated to html.
Each article is of a specific type. The categories used include:
Currently the documentation system assumes a flat hierarchy and assertions to leaf nodes. The vocabulary used for the above is not yet stable.
Any properties can be used, but the recommended set is:
The publishing status ontology (pso) is used to give each article a status such as 'initial-draft'
Each article can be references multiple times in the main ontology, in different ways.
Sometimes a class may point to an article - for example, if an ontology class implements a certain design pattern or template described in an article, then a 'implements design pattern' annotation property connects the two.
Sometimes it may be more appropriate to link an axiom annotation to an article.
It is not always appropriate to cram everything into a single article that is embedded in the ontology. The seeAlso property can be used to connect out to googledocs, spreadsheets, ontogenesis articles, textbooks, etc.
Articles can be viewed when references.owl is loaded alongside the main ontology in the ontology editing environment, but this is not appropriate for everyone.
Each article can be viewed on the web via its purl
Ontology editors should edit the file references-edit.omn in git - any new articles created should be in their idrange - see uberonref-idranges.owl.
The file can be edited in a text editor (the recommended text editor emacs plus Phil Lord's omn-mode.el, plus ubref-helper.el). Note that the author should be adept in manchester notation.
The prefered route is to open the articles ontology in Protege, navigating to the 'individuals by type' tab (insert image here).
Screenshot
In both cases, the main text should go in the dc:description tab using markdown format. Note that hashes should be used for headings rather than underlines.
The format used is a variant called ontology markdown. Class labels can be written in backtics - the derived documentation will make PURL links from these (to be implemented).
In general each article type should follow a certain template (to be documented).
The ontology release manager will generate the derived documentation from this file.
The current implementation is somewhat ad-hoc and may be replaced.
The references-edit.omn is translated to an rdf/owl ontology - references.owl
A perl script (owldoc2md.pl) generates individual markdown (.md) files from this owl file (using a to-be-released API). It assumes some of the annotation properties listed above are used.
Each markdown file is then converted to an html file using pandoc.
The html file has the same name as the localname of the URI. It is committed to svn, and the svn property svn:mime-type is set to text/html
This system was inspired by Matt Brush's REO documentation system developed at OHSU, and by David Osumi-Sutherland's org-mode system, as well as by Phil Lord's articles on ontology documentation and applying literate programming ideas to ontologies.