search

tibonto / aeon

The Academic Event Ontology (AEON) can be used to represent information regarding academic events.
https://tibonto.github.io/aeon/
Creative Commons Attribution 4.0 International
14 stars 4 forks source link

Maintain ontology documentation in an editable way #43

Closed clange closed 2 years ago

clange commented 3 years ago

From #11 we have a Word version of the ontology's documentation in VoCol. But how are we going to evolve that? Wouldn't it make more sense to have it as an HTML file in this repository, such that we could more easily track changes using git?

StroemPhi commented 3 years ago

Having a .docx was due to need it there fast, for the case when the VoCol instance deletes it without a reason. But I totally agree that we need to improve the documentation here using git. But instead of html wouldn't mark down suffice and there is also the possibility to use the wiki here.

andrecastro0o commented 3 years ago

@StroemPhi if you send me the link do to the docx i can convert to .md and add it to the wiki here, or simply doc/ with .md files. Whatever is best

clange commented 3 years ago

Makes sense. Then I think an .md file in this directory will work best, because it's version-controlled and can be edited locally. Well, wikis can also be cloned but it's a bit trickier.

StroemPhi commented 3 years ago

@andrecastro0o thank you they are here (https://github.com/tibonto/aeon/tree/master/tibonto_docs) and I guess it wasn't really smart of me to call the folder docs, as it's not really documentation. This are just the texts used in the http://ontology.tib.eu/aeon/ instance, which unfortunately has a bug, that will delete the text in the home and data policy tab, when you login to edit things.

StroemPhi commented 3 years ago

But I guess the text in "https://github.com/tibonto/aeon/blob/master/tibonto_docs/Academic%20Event%20Ontology.docx" should definitely be used insted of the stub that is the recent README.md.

andrecastro0o commented 3 years ago

nice, and we you want publish the docs in bit more fancy HTML we can have to md -> HTML pipeline with something like Sphinx / pandoc / jinja.

andrecastro0o commented 3 years ago

In https://github.com/tibonto/aeon/tree/issue43_ontology_documentation Read is updated with the content of the .docx

StroemPhi commented 3 years ago

README has been updated with PR https://github.com/tibonto/aeon/pull/56

StroemPhi commented 2 years ago

can be closed, as we've switched to an ODK workflow including the automatic building of docs with #149, see also https://tibonto.github.io/aeon/. a new issue will have to be opened regarding the still missing content of the docs