Principle: Adequate Documentation [1]

This is trivial to understand. The documentation for an ontology is very important for adoption and for data sharing. This works for software as well. One thing I found always awesome regarding Java was the quality of the API documentation, the JavaDocs are cool and easy to generate. For ontologies the reality is a bit more complicated.

Some ontologies, including some of those I made, are just the pure RDFS/OWL file. Often with no descriptions whatsoever of the classes/properties. The understanding of those ontologies relies totally on the ability of the users to interpret the labels/names correctly. Other ontologies include very fuzzy, sometimes poor, descriptions - "Document: a document. The Document class represents those things which are, broadly conceived, 'documents'.". The interpretation relies mostly on the users' common sense. To be fair, in recent versions of the FOAF vocabulary, the previous definition is accompanied by a note saying: "We do not (currently) distinguish precisely between physical and electronic documents, or between copies of a work and the abstraction those copies embody. The relationship between documents and their byte-stream representation needs clarification". And let's be honest, defining what a document is nowadays, in the digital era, is not trivial. Is every file a document?

In the case of OBO Foundry, a set of principles has been defined. Here are some of them:

"The ontologies include textual definitions for all terms. Many biological and medical terms may be ambiguous, so terms should be defined so that their precise meaning within the context of a particular ontology is clear to a human reader."

"The ontology is well documented."

The thing is, definitions are a necessary step but that is not enough. When I talk about 'Adequate Documentation' I mean many different things: definitions, examples of use cases, examples of resulting triples, motivations, related projects... In other words, a good amount of shared knowledge about the ontology and the process that generated it.

Unfortunately there are no clear rules, I keep trying different ways of translating the most tacit knowledge I can into explicit and I can't say I found the right recipe yet. Definitions can certainly help, I find valuable to include explanations of the ontology building process where motivations behind the different choices are given, explanatory figures, plenty of examples with actual triples, maybe a list of Frequently Asked Questions where the authors can publicly address some of the concerns of real users. All this takes time and effort, and, by personal experience, can also cause collateral damage...

Which principles drive ontology adoption?

Several weeks ago, I started to think of the next version of the Annotation Ontology (AO). After one year spent developing the Annotation Framework and discussing with several colleagues and friends, I certainly have a little list of things I want to improve. Nothing major, mostly a clean up.

Before proceeding with the updates, I wanted to better clarify the set of principles I want to follow in developing AO2. These are, in random order: Traceability, Orthogonality, Generality, Interoperability, Modularity, Extensibility, Adequate Documentation, Community Driven. The reason why I am listing this principles is important, I believe they influence adoption.

As you might have noticed the number of available ontologies is constantly increasing. If you need to use an ontology, you have to go through the process of revising what is out there, and selecting what you think is most appropriate. How many time have you done that? How many time did you succeed? How many times did you find the right ontology covering exactly what you needed? I am pretty sure that if you are involved in the development of a complex application the answer is something like: I found a few ontologies I could mix and match... I still need to add pieces... and, most importantly, I am not sure I agree on the way some or them are done. Right. Welcome to the Semantic Web I would say.

I remember the old days - many years ago - when Dublin Core Metadata Element Set, Version 1.1 (DC) was the answer to almost everything. When I started working on SWAN (Semantic Web Applications in Neuromedicine) in 2006 I found immediately DC to be insufficient for our needs. For days I've been struggling trying to understand what to do: use DC and being sloppy or create something more appropriate risking isolation and to increase the entropy of the Semantic Web world.

Well at that time my answer has been the Provenance, Authoring and Versioning Ontology (PAV) now available in version 2. The choice, at the time, has been dictated also by practical reasons: if I was using DC for Annotation Properties and I wanted to be OWL DL, I could not use it also for other properties. Since then, PAV has been used in our applications but also in several others developed by people/groups I barely know - sometimes I wish they just would tell me something like: "hey I am using PAV and it's cool" or even "hey I am using PAV and it sucks because...". PAV has also been considered as one of the starting points for the W3C Provenance Incubator Group.

PAV was not such a bad idea at the end. But it was a risky business. If you are developing an application you need always to keep an eye on what is existing and the other eye on your requirements. This results to be even more complicated because it is hard to find appropriate ontologies and, when you find them, they often don't have adequate documentation for you to understand that is what you are looking for. Surprise! The  lack of shared knowledge about the ontology does not help it to emerge and does not help adoption... unless, of course, external factors - networking, important supporters, big institutions ... - come into play. And external factors are not little thing.