INCATools / INCATools/ontology-development-kit

Revise documentation

Open
#1,330 0 comments 1 reaction 1 assignee Claimed by @gouttegd View on GitHub
documentation
Dominant language
Dockerfile
Stars
375
Forks
69
Avg merge
3d 5h
Merged PRs (30d)
7

Description

The documentation should be revised to ensure it is still accurate (this should in fact be done periodically, probably at least once during every development cycle).

Some issues spotted with existing documentation:

* In the [README-editors.md](https://github.com/INCATools/odkcore/blob/main/src/incatools/odk/templates/src/ontology/README-editors.md.jinja2) template:
* Link to James Overton’s [OBO tutorial](ttps://github.com/jamesaoverton/obo-tutorial), which was itself last updated 7 years ago
* Link to the [Gene Ontology Editors Tutorial](https://go-protege-tutorial.readthedocs.io/en/latest/), which was last updated 9 years ago
* Those resources might still be somewhat useful, but we need to balance their usefulness with the risk that they can lead users astray with outdated advice – at this point I think it’s probably better to send users only to the OBOOK.
* In the [EditorsWorkflow.md](https://github.com/INCATools/odkcore/blob/main/src/incatools/odk/templates/_dynamic_documentation.jinja2) template:
* Recommends using the infamous `-B` option: `sh run.sh make prepare_release -B` (gentle reminder that every time someone recommends using that option, somewhere in the world a Make developer dies – and it’s not as if there were enough Make developers to begin with that we could afford to lose them like that!).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.