Ontology Documentation Tools and Workflows

Mike's Notes

Marcelo Xavier started a fascinating discussion on the Ontolog Forum about creating online documentation for an Ontology. My friend Alex Shkotin used Gemini to identify a possible solution. Nico Matentzoglu also made valuable ponis including suggestions around using Diataxis. OBOOK (Open Biological and Biomedical Ontologies Organised Knowledge) is a fantastic resource and a great example of how to organise successful training material.

I have copied the whole thread here, along with the resources, for future reference. I can use all of this in future development of the Pipi Ontology Engine (ont).

Dear community,

I would like to kindly request suggestions on the best way to create online documentation for an ontology currently being developed in WebProtégé.

We are looking for tools or approaches that enable us to share the progress and structural details of the ontology in a clear and accessible manner for all stakeholders involved.

Thank you very much in advance for your help and recommendations.

Sincerely,

Marcelo Xavier

"Dear Marcelo,

I am personally for self documented code, then we need one or another rendering engine. Did you ask OBO Foundry and [protege-user] list?

I asked Gemini, have a look https://gemini.google.com/share/6e091b60d275

Best,

Alex"

Dear Marcelo,

Unfortunately I cannot answer your question for WebProtege specifically; Note that independently of your issue (and despite this: https://github.com/protegeproject/webprotege/issues/284), I would urge anyone developing an ontology regardless of where it is curated/edited to use a standard version control system like GitHub or GitLab for community engagement and "open science best practice" (standard workflows, etc).

A lot of OBO ontologies use the Ontology Development Kit (ODK) which comes with some built-in functions to generate an mkdocs (material-themed) documentation scaffolding which can then be extended by the ontology team. This is usually deployed on github.io (which you seem to have some personal experience with as well). Some of our docs pages are very detailed, others vanilla, see for example:

https://obophenotype.github.io/uberon/

https://obophenotype.github.io/human-phenotype-ontology/

https://oborel.github.io/obo-relations/

We mostly curate our documentation manually, but claude code or similar can, with some guidance and careful review, generate quite reasonable pages as well. 

On a more personal note:

- I like the clarity of the diataxis framework (https://diataxis.fr/) for organising docs, which we more or less try to follow in OBO Academy (https://oboacademy.github.io/obook/). 

- I really like it if modelling patterns in the ontology are documented explicitly using something like DOSDP: https://github.com/monarch-initiative/mondo/blob/master/src/patterns/dosdp-patterns/autoimmune.yaml. It is trivially possible to generate documentation pages from these to have something like this: https://mondo.readthedocs.io/en/latest/editors-guide/patterns/ (I find this is, if I may be so bold, the most important part of ontology documentation - even though hardly anyone does it).

Good luck!

Nico

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

16/01/2026

Ontology Documentation Tools and Workflows

By: Alex Shkotin
Gemeni: 14/01/2026

Alex is an independent researcher in Moscow.

Gemini

Some responses below were generated according to the creator's saved info and preferences. Learn moreOpens in a new window 14 January 2026 at 21:51

Published on 14 January 2026 at 21:53

Prompt

request suggestions on the best way to create online documentation for an ontology currently being developed in WebProtégé.

We are looking for tools or approaches that enable us to share the progress and structural details of the ontology in a clear and accessible manner for all stakeholders involved.

Output

Creating online documentation for an ontology in WebProtégé is a common challenge, as the platform is excellent for editing but doesn't have a built-in "one-click" public documentation site.

To share structural details with stakeholders, the best approach is to export your ontology from WebProtégé and then use a specialized documentation generator. Here are the most effective tools and methods for 2026.

1. Top Documentation Tools

Once you export your ontology (usually in Turtle or RDF/XML format), use one of these tools to generate a human-readable website.

Tool Best For Key Features
WIDOCO Standard-compliant Docs A "Wizard" that generates a complete HTML site with metadata, cross-references, and a visual diagram (via WebVOWL).
LODE Quick Previews A web service that turns an OWL file into a single, clean HTML page. Great for non-technical stakeholders to read class definitions.
WebVOWL Visual Stakeholders Provides an interactive, graphical view of the ontology. Excellent for showing relationships and hierarchy visually.
OnToology Automated Workflows If you use GitHub, this tool automatically runs WIDOCO and WebVOWL every time you push a change to your repository.

2. Recommended Workflow: The "Professional" Route

If you want a live site that stays updated as your team works in WebProtégé, follow these steps:

  1. Export from WebProtégé: Go to Project > Export and select the Turtle (.ttl) or RDF/XML format.
  2. Upload to GitHub: Create a repository for your ontology.
  3. Use WIDOCO: Run the WIDOCO wizard. It will ask you for a title, description, and logo. It then generates a folder full of HTML files.
  4. Host on GitHub Pages: Enable GitHub Pages on your repository to turn that folder into a public URL (e.g., https://your-org.github.io/ontology-doc).

3. Collaborative Alternatives (Internal)

If you aren't ready to publish a full website yet, you can use WebProtégé’s internal features to keep stakeholders in the loop:

  • Sharing & Permissions: You can invite stakeholders to the WebProtégé project with "View Only" or "Comment Only" permissions. This allows them to see the structure without accidentally changing anything.
  • Threaded Comments: Use the "Comments" tab in WebProtégé to discuss specific classes or properties. Stakeholders can leave feedback directly on the entity they are concerned about.
  • Project Feed: This provides a timeline of changes, which is helpful for stakeholders to see the "velocity" of the project and what has been added recently.

4. Enriching Your Documentation

For any documentation tool to work well, stakeholders need clear descriptions. Ensure your team fills out these Annotation Properties in WebProtégé for every class and property:

  • rdfs:label: A human-friendly name (e.g., "FinancialTransaction" vs "financial_transaction").
  • rdfs:comment or skos:definition: A clear, non-circular definition of the concept.
  • dc:creator: To show who is responsible for that part of the model.

Would you like me to help you draft a set of "Documentation Best Practices" for your team to follow within WebProtégé to ensure the final output is high quality?

By ,
Tags , , , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)