Home.md

@@ -12,8 +12,11 @@ The idea behind the EM_Glossary is to offer community accepted, harmonised domai
   alt="EM-Glossary interoperabiltiy" />
 
 ### Why OWL?
-OWL is the [Web ontology language](https://www.w3.org/OWL/) is a Semantic Web language designed to represent rich and complex knowledge about things, groups of things, and relations between thing) and designed OWL is part of the W3C’s Semantic Web technology stack, which includes RDF, RDFS, SPARQL, etc.
+OWL is the [Web ontology language](https://www.w3.org/OWL/). It is the semantic web language and designed as part of the W3C's _semantic web technology_ stack including RDF, RDFS, SPARQL and others. 
 
+OWL is designed to represent rich and complex knowledge about things, groups of things, and relations between thing). Resources represented in OWL can be easily integrated and referenced in other semantic resources - below we give recommendations towards technical adoption of our owl artefacts in metadata schemas, semantic file formats or other OWL based semantic artefacts. 
+
+---
 # How to adopt
 The EM-Glossary provides stable domain-level semantics for adoption into or alignment of application level semantics and other academic use. We envision different levels of adoption. 
 ## textual & oral use
@@ -39,27 +42,27 @@ How to adapt and use terminology from emg.owl in your application level artefact
 - how to technically adopt
 - how we expect to be acknowledged
 
+----
 
+# Release documentation of emg.owl
+The current artefact is documented in our [Glossary specification page](owl.emglossary.helmholtz-metadaten.de). Here we provide additional info on planned release cycle, file management during releases and versioning applied to our releases.
 
-# Documentation of emg.owl 
-
-
-
-### Emg.owl release cycle & management
+### emg.owl release cycle & management
 For release cycle, release management and [semantic versioning](https://semver.org/) we follow generally established best practices for the emg.owl artefact. We intend to keep the semantic artefact stable through short release cycles. Depending on the our community process we expect at least 3 major releases per year. 
 
 Prior release, changes are accumulated in [emg-edit.owl](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/blob/main/development/emg-edit.owl) which is assembled in this repository. Every merge to main in our [community repository](https://codebase.helmholtz.cloud/em_glossary/em_glossary) triggers an automated update of emg-edit.owl through a CI/CD pipeline (see below). When a release is made, version information is included in the OWL header and [emg.owl](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/blob/main/emg.owl) and its [documentation](owl.emglossary.helmholtz-metadaten.de) is updated. Previous versions of emg.owl are archived within [this repository](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/tree/main/previous-versions). 
 
-### Emg.owl versioning
+In the future we intend to handle file changes and semantic versioning during releases automatically through a separate script.
+
+### emg.owl versioning
 Version number is indicated in the OWL header. Further we generate versions IRIs consisting of base URI and version number, that deference to the respective version of the artefact. Previous versions are archived in this repository. 
 
-Our version number are in the form of X.Y.Z . X indicates _major version_ - related changes may include the addition or removal of classes or substantial changes to the hierarchy or relations. Y indicates _minor versions_ - related changes can include content changes e.g. of definitions or annotation properties that may adjust semantic meaning of a class. Z indicates _patches_ which may include changes in spelling, changes of annotation properties that doe not change semantic meaning.
+Our version number are in the form of _X.Y.Z_ . _X_ indicates _major version_ - related changes may include the addition or removal of classes or substantial changes to the hierarchy or relations. _Y_ indicates _minor versions_ - related changes can include content changes e.g. of definitions or annotation properties that may adjust semantic meaning of a class. _Z_ indicates _patches_ which may include changes in spelling, changes of annotation properties that doe not change semantic meaning.
 
 A list of all changes compared to previous version is given in our [Glossary specification page](owl.emglossary.helmholtz-metadaten.de).
 
 ### OWL build pipeline
-the owl-edit file is build automatically from the yaml files in our repo
-external vocabularies are set up in the empty.owl
+The classes, class hierarchy and annotation properties are all sourced from the [yaml files](https://codebase.helmholtz.cloud/em_glossary/em_glossary/-/tree/main/terms) that are the output of our community process. Every merge to main in our [community repository](https://codebase.helmholtz.cloud/em_glossary/em_glossary) triggers a a CI/CD pipeline that automatically assembles [emg-edit.owl](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/blob/main/development/emg-edit.owl). Keys for annotation properties are sourced from external well established vocabularies which are set up in [empty.owl](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/blob/main/development/empty.owl), mappings are defined in [yaml_to_owl.py](https://codebase.helmholtz.cloud/em_glossary/em_glossary_owl/-/blob/main/development/yaml_to_owl.py) which is also the routine which carries out parsing.
 
 # other info