search

OpenEnergyPlatform / ontology

Repository for the Open Energy Ontology (OEO)
Creative Commons Zero v1.0 Universal
105 stars 20 forks source link

Restructure and improve wiki #1106

Open markus-rothkoetter opened 2 years ago

markus-rothkoetter commented 2 years ago

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.

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.

Aspects to address IN THE FUTURE ⏳

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

Aspects resolved IN THE PAST 🎉

Things that are already done.

l-emele commented 2 years ago

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 commented 2 years ago

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

markus-rothkoetter commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 1 year ago

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 commented 1 year ago

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.