Restructure and improve wiki

[markus-rothkoetter]

Description of the issue

The current wiki contains some work-in-progress pages as well as bugs like broken links etc. I'd like to improve and standardise the wiki.

This issue is meant to be a collection of aspects to address (bugs, ideas, comments, ...) As soon as an aspects gets concrete I think it's best to open a dedicated issue.

• 🐙 links to issue
• 📚 links to wiki-page
• 💬 links to comments in this issue, which introduce the aspect

I'll keep the lists in this issue description up-to-date. 🚀 reactions on comments, indicate that I added the aspect to the list.

Aspects to address NOW 🦾

Things that are planned to be done now.

• [ ] add "wiki-workflow" page

Aspects to address IN THE FUTURE ⏳

Things that are NOT prioritised, yet, or are NOT outlined concretely.

• [ ] fix broken links in wiki sidebar
• [ ] add 🤖 script for diffs
• [ ] extend BFO description (tree-view)
• [ ] separate extensive sections from CONTRIBUTING.md and include these in the wiki
• [ ] remove redundant TOC-pages / deep nesting (decreases maintenance effort)
• [ ] refactor short subpages 💬

Aspects resolved IN THE PAST 🎉

Things that are already done.

• [x] add module import script description 📚 Wiki | 🏁 @2022-08-30
• [x] create add basic WIP-banner
• [x] add pull-request workflow page
• [x] add ROBOT to 📚 Wiki | 🏁@2022-04-19
• [x] add page "add yourself as contributor" to 📚 Wiki | 🏁@2022-05-03
• [x] refine content in "pull-request-workflow" (📚 Wiki | 🏁@2022-05-09

[l-emele]

Some wiki pages are very short, e.g. the subpages on the use cases: https://github.com/OpenEnergyPlatform/ontology/wiki/use-cases . I think, those very short pages that only include of one or two sentences should be included in other pages.

[stap-m]

Can this be implemented (partly) before the next release?

[markus-rothkoetter]

Things in the NOW-section: ✔Yes :) I'll address these, after I'm done with the two/three PRs (issues) I'm currently assigned.

IN THE FUTURE-section things: Not before the next release.

[l-emele]

I only had today the chance to look into the changes of the wiki. The idea was to improve the wiki and not do introduce completely new workflows. Workflow changes should be discussed beforehand. Therefore e.g. I changed on the page https://github.com/OpenEnergyPlatform/ontology/wiki/Supplementary-Checklists that the persons that are involved in the issues are the ones who should review a PR.

Additionally, I think, the usage of emojis in the write place can be helpful. But scattering everything with emojis is at least for me very distracting and makes things hard to read.

[markus-rothkoetter]

Additionally, I think, the usage of emojis in the write place can be helpful. But scattering everything with emojis is at least for me very distracting and makes things hard to read.

No problem. I adopted the Emoji-Style from the CONTRIBUTING.md, and added some additional ones where I thought it might be appropriate. I'll remove the additional ones. Thank you for the input!

.... not do introduce completely new workflows. Workflow changes should be discussed beforehand.

I absolutely agree on dicussing workflows first. So, I did not introduce a new workflow except for the "Reviewer-perspective". Especially, the example you mentioned is listed in the current CONTRIBUTING.md as no. 11 under "Review"-section.

Maybe we can think about a short meeting that we can have a look at the current documentation, so that you can comment on their up-to-dateness?

[Alex2448]

I think it is a good idea to mention in the PR-Guideline to wait for a second review if the PR is too large (maybe set a rule for >100 lines or if many concepts are introduced).

Also, sometimes there are some things decided that I did not know and did not follow where to find it. For example, to not use the language @en annotation for labels or definitions . I think this should be mentioned in how to add annotations to a class or how to use protégé since sometimes protégé automatically adds them.

[stap-m]

I think it is a good idea to mention in the PR-Guideline to wait for a second review if the PR is too large (maybe set a rule for >100 lines or if many concepts are introduced).

I just saw, that Contributing.md is also ambiguous here and should be clarified aswell.