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 points, 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).
Update
Michael DeBellis provided an alternative approach and an example for documenting using Widoco.
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
I'm not sure I understand the question. There isn't anything special about an ontology developed in WebProtege. Well except that (at least IMO) developing an ontology and ONLY using WebProtege is a really bad idea. WebProtege doesn't support reasoners so you can't define axioms on classes, SWRL rules, etc. If you aren't going to use the cool stuff from OWL why use OWL at all? Go with something like just RDF or Neo4J. It's like asking "are there any tools for documenting code written using PyCharm?" The IDE shouldn't dictate how you document your code and the tool you use to develop your ontology shouldn't dictate how you document it.
But IMO, the clear answer... at least a very good answer is Widoco which is the same tool that many people use already to document ontologies: https://github.com/dgarijo/Widoco You can export your ontology from WebProtege and use Widoco. One thing to look out for, at least this confused me for a long time, is if your ontology is just on your local file system (although it sounds like that isn't an issue for you) and you use Widoco the results will be virtually empty documentation. This isn't because of a limitation of Widoco, actually I guess in some ways it is, it is because Widoco is designed for ontologies that are hosted on the Internet and if you don't currently host on the Internet but on your local file system Widoco will generate your documentation but when you try to look at it your Operating System will block it and it will look mostly empty. One way around that is to host Widoco documentation on GitHub. Which IMO is a much better solution in the long term than leaving it in WebProtege. WebProtege is a great collaboration tool but doesn't have the support for real software development like branching, merging, issues, etc. that GitHub does. Here's an example where I did that for an ontology I developed last year on the social science research called Climate Obstruction: https://mdebellis.github.io/Climate_Obstruction/
Also, in my revision of the Pizza Tutorial: https://www.michaeldebellis.com/post/new-protege-pizza-tutorial I added a chapter (chapter 11) that talks about Web Protege and how you can go back and forth between WebProtege and Desktop Protege which is what I recommend. That way you get the collaboration features of WebProtege but you can write axioms and get other features only available on the Desktop version of Protege. The nice thing is that WebProtege was designed to do what we used to call in the CASE world "round trip engineering" I.e., you can export the ontology, make changes in Desktop Protege (and/or other tools) then re-import the ontology into WebProtege and the changes are a part of the WebProtege history as if you made them in WebProtege. Also, WebProtege does some odd things to IRIs that I talk about in the tutorial.
Cheers,
Michael
Resources
- https://gemini.google.com/share/6e091b60d275
- https://groups.google.com/g/ontolog-forum/c/aY3HoW1QURQ
- https://groups.google.com/g/ontolog-forum/c/aY3HoW1QURQ/m/mR_Q2Wj5BwAJ
- https://github.com/dgarijo/Widoco
- https://bokcenter.harvard.edu/flipped-classrooms
- https://www.blog.ajabbi.com/2025/11/what-is-diataxis-and-should-you-be.html
- https://www.blog.ajabbi.com/2025/03/learning-object-integration-with-cms.html
- https://www.linkedin.com/in/ashkotin/
- https://mdebellis.github.io/Climate_Obstruction/
- https://github.com/dgarijo/Widoco
- https://www.michaeldebellis.com/post/new-protege-pizza-tutorial
References
- Reference
Repository
- Home > Ajabbi Research > Library > Subscriptions > Ontolog Forum
- Home > Handbook >
Last Updated
29/01/2026
Ontology Documentation Tools and Workflows
Alex is an independent researcher in Moscow.
https://www.linkedin.com/in/ashkotin/
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:
- Export from WebProtégé: Go to Project > Export and select the Turtle (.ttl) or RDF/XML format.
- Upload to GitHub: Create a repository for your ontology.
- 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.
- 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?
No comments:
Post a Comment