Merge pull request #4 from meaningfy-ws/feature/EPO-831

WIP: Documentation updates from feedback

docs/modules/ROOT/pages/epo-context.adoc

@@ -1,19 +1,19 @@
 [[sec:introduction]]
-== model2owl in eProcurement context
+== Relation to ePO
 
-This document provides a working specification of the guidelines and conventions for the eProcurement conceptual model, such that it qualifies as suitable input for the transformation scripts meant to generate the formal eProcurement ontology.
+This section provides the motivation for the https://github.com/OP-TED/model2owl/[*model2owl*] software project within the https://docs.ted.europa.eu/EPO/latest/business.html[eProcurement Ontology (ePO)] project. The business context and the project overview are detailed in the https://docs.ted.europa.eu/epo-home/ePO_Arch_Design.html[eProcurement ontology architecture and formalisation specifications].
 
-The business context and the project overview are detailed in [xref:references.adoc#ref:costetchi2020a[costetchi2020a]], while the next section provides the motivation and situates the current document within the project.
+We provide here a working specification of the guidelines and conventions for the eProcurement conceptual model, such that it qualifies as suitable input for the transformation scripts meant to generate the formal eProcurement ontology. The https://github.com/OP-TED/model2owl/[*model2owl*] toolset, which hosts these transformation scripts, is therefore an integral part of the ePO project.
 
 === Background
 
 In the eProcurement ontology project, the conceptual model was decided [xref:references.adoc#ref:d2.01-2017[d2.01-2017]] to be represented in _Unified Modelling Language (UML)_ [xref:references.adoc#ref:uml-userguide[uml-userguide]]. It is a visual representation language that facilitates understanding and convergence between stakeholders towards a common conceptualisation of the model.
 
-Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[fowler2004]] for ontology design is in the specification of class diagrams initially conceived for object-oriented software. UML does not define a formal semantics that would permit to determine, from the class diagrams, whether an ontology is consistent, or to determine the correctness of the ontology implementation. Semantics in such cases becomes a subject to interpretation by the stakeholders involved in the development process and later by the users in the application and integration tasks [xref:references.adoc#ref:grunninger2003[grunninger2003]].
+Generally, the primary application of UML [xref:references.adoc#ref:fowler2004[fowler2004]] for ontology design is in the specification of class diagrams, a design formalism initially conceived for object-oriented software. UML does not define a formal _semantics_ that would permit to determine, from the class diagrams, whether a corresponding ontology is consistent, or to determine the correctness of the ontology implementation. Semantics in UML is therefore subject to interpretation by the stakeholders involved in the development process, and later by the users in the application and integration tasks [xref:references.adoc#ref:grunninger2003[grunninger2003]].
 
-On the other hand, UML is closer than more logic-oriented approaches to the programming languages in which enterprise applications are implemented. For this reason the current specification establishes conventions for interpretation of the UML-based conceptual model.
+Yet, UML is closer than more logic-oriented approaches to the programming languages in which software applications -- typically https://en.wikipedia.org/wiki/Enterprise_software[enterprise applications] -- are implemented. For this reason, the current specification establishes conventions for interpretation of the UML-based conceptual model.
 
-The UML Conceptual Model of the eProcurement domain serves as the single source of truth, which means that the formal eProcurement ontology is derived from it through a model transformation process. It is possible to generate automatically the formal ontology in RDF format [xref:references.adoc#ref:rdf11[rdf11]] from the XMI (v.2.5.1) serialisation [xref:references.adoc#ref:xmi2.5.1[xmi2.5.1]] of a UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that xref:transformation/uml2owl-transformation.adoc[a set of clear transformation rules] are established, and that xref:uml/conceptual-model-conventions.adoc[a set of modelling conventions] is respected.
+The UML Conceptual Model of the eProcurement domain serves as the single source of truth, which means that the formal eProcurement ontology is derived from it through a model transformation process. It is possible to generate automatically the formal ontology in RDF format [xref:references.adoc#ref:rdf11[rdf11]] from the XMI (v.2.5.1) serialisation [xref:references.adoc#ref:xmi2.5.1[xmi2.5.1]] of a UML (v.2.5) model [xref:references.adoc#ref:uml2.5[uml2.5]], provided that xref:uml/conceptual-model-conventions.adoc[a set of modelling conventions] is respected, and that xref:transformation/uml2owl-transformation.adoc[a set of clear transformation rules] is established.
 
 This document provides the UML modelling constraints and a set of conventional and technical recommendations for naming and structuring the UML class diagram elements: packages, classes, data types, enumerations, enumeration items, class attributes, association relation and dependency relation. These will be addressed contextually in the subsections of xref::uml/conceptual-model-conventions.adoc[UML conventions specification].
 
@@ -27,12 +27,12 @@ The eProcurement conceptual model must fulfil mainly four fundamental objectives
 * Provide a point of reference for system designers to gather system specifications and documentation.
 * Serve as input for development of a (more) formal model.
 
-In order to support objectives a conceptual model should fulfil the following requirements.
+In order to support the objectives, the eProcurement conceptual model must fulfil the following requirements:
 
-* Be available to all team members, to facilitate collaboration and iteration.
+* Be available to all stakeholders, to facilitate collaboration and iteration.
 * Be easily changeable, as a continuous reflection of up-to-date information.
 * Contain both visual and written forms of diagramming, to better explain the abstract concepts it may represent.
 * Establish relevant terms and concepts that will be used throughout the project.
-* Define said terms and concepts.
-* Provide a basic structure for entities of the project.
+* Define terms and concepts.
+* Provide a basic structure for the conceptual entities of the project.
 * Reduce the ambiguity while maintaining a simple and concise encoding.

docs/modules/ROOT/pages/index.adoc

@@ -8,9 +8,9 @@
 :docinfo: shared
 
 
-The https://github.com/OP-TED/model2owl/[*model2owl*] project comprises a set of tools for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/meaningfy-ws/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification].
+The https://github.com/OP-TED/model2owl/[*model2owl*] software project was conceived as part of the https://docs.ted.europa.eu/EPO/latest/business.html[eProcurement Ontology (ePO)] public procurement digitization project of the https://en.wikipedia.org/wiki/Publications_Office_of_the_European_Union[Publications Office of the European Union (OP)]. It comprises a _toolset_, or set of https://en.wikipedia.org/wiki/Programming_tool[programming tools], for transforming an UML (v2.5) model from its XMI (v2.5.1) serialisation into a formal OWL ontology, and a SHACL shape. This approach is conformant to the https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide] and with https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[eProcurement Ontology Architecture specification].
 
-The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in the https://meaningfy-ws.github.io/model2owl-docs/public-review/uml/conceptual-model-conventions.html[EPO UML conventions specification]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide].
+The UML transformation is performed using XSLT stylesheets under the assumption that the UML model conforms to the set of conventions outlined in xref:uml/conceptual-model-conventions.adoc[ePO UML conventions]. This set of UML conventions is aligned with and extends the UML conventions specified in https://semiceu.github.io/style-guide/1.0.0/index.html[SEMIC Style Guide]. Validation rules for the transformation confirm the conformance to these conventions.
 
 The following capabilities are implemented:
 
@@ -20,14 +20,11 @@ The following capabilities are implemented:
 * UML -> OWL 2 (heavyweight ontology with additional axioms suitable for reasoning purposes)
 * UML -> SHACL (data shapes suitable for representing an application profile)
 
-This documentation is evolving and aims at covering the important aspects that one might be interested in when using these tools, including:
+This documentation is evolving and aims at covering the following aspects related to use of these tools:
 
-* The architectural setup of the project and the ontology
+* The architectural setup of the toolset and the ontology
 * The conceptual model conventions that the UML model should adhere to, in order to enable the tools to generate the best possible results.
 * The transformation rules applied in the process of conversion.
-* The set of validation rules that realise the established conventions (and UML interpretations).
-
-This work is developed in the context of https://github.com/eprocurementontology/eprocurementontology[eProcurement ontology project] financed by the Digital Europe Programme and led by the https://op.europa.eu/en/[Publications Office of the European Union].
-
-The tools can be used on any other ontology that is built according to the provided https://github.com/meaningfy-ws/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions].
+* The set of validation rules that check a transformation's conformance to the established conventions (and UML interpretations).
 
+The tools can be used on any other ontology that is built according to the provided https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf[modelling architecture] and xref:uml/conceptual-model-conventions.adoc[UML conceptual model conventions].

docs/modules/ROOT/pages/references.adoc

@@ -89,7 +89,7 @@ Kunze, John, and Thomas Baker. 2007. “The Dublin Core Metadata Element Set.”
 
 - *[[[ref:semic-style-guide]]semic-style-guide]* SEMIC Style guide v1.0.0, 2023, https://semiceu.github.io/style-guide/1.0.0/index.html
 
-- *[[[ref:epo-arch]]epo-arch]* Costetchi, E. (2020). EProcurement ontology architecture and formalisation specifications. Recommendation, Publications Office of the European Union. Available at: https://github.com/OP-TED/model2owl/blob/master/doc/ontology-architecture/ontology-architecture.pdf
+- *[[[ref:epo-arch]]epo-arch]* Costetchi, E. (2020). EProcurement ontology architecture and formalisation specifications. Recommendation, Publications Office of the European Union. Available at: https://github.com/OP-TED/model2owl/blob/master/docs/ontology-architecture/ontology-architecture.pdf
 
 - *[[[ref:oslo-rules]]oslo-rules]* Thijs, G. (2019) OSLO MODELLERINGSREGELS. Available at: https://github.com/Informatievlaanderen/OSLO-handleiding/blob/master/Modellering/OSLO-Modelleringsregels.pdf
 

docs/modules/ROOT/pages/uml/definitions.adoc

@@ -1,21 +1,21 @@
 [[sec:definitions]]
 == Preliminary definitions
 
-In this document three closely related and mostly overlapping domains are used interchangeably. They come from the worlds of: _enterprise architecture_, _software engineering and design_ and _formal knowledge representation_. It is therefore necessary to establish the terms, especially the common ones, by defining what they mean in each of these domains.
+This documentation makes references to three closely related and overlapping domains. They come from the worlds of: _enterprise architecture_, _software engineering and design_ and _formal knowledge representation_. It is therefore necessary to establish the terms, especially the common ones, by defining what they mean in each of these domains.
 
 [[sec:cm]]
 === Conceptual Model
 
-A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]]. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive, rather than restrictive. That is why each concept needs to be well named by providing preferred and alternative labels, and a clear and precise definition supported by examples and explanatory notes.
+A _conceptual model_ is a representation of a system that uses concepts to form said representation. A _concept_ can be viewed as an idea or notion; a unit of thought [xref:references.adoc#ref:skos-spec[skos-spec]] in the mind, which can be put into writing -- _realized_ as a representation -- in various forms (such as part of a diagram or mind map). A concept on paper needs to be well named by providing as many understandable labels as necessary (for example, multiple different expressions or languages), supported by a clear definition with examples and explanatory notes.
 
-The conceptual model comprises representations of concepts, their qualities or attributes and relationships to other concepts. Most commonly these are association and generalisation relations. In addition, behaviour can be represented, ranging from the concept level up to the level of the system as a whole. Behavioural aspects, however, fall out of the scope in the current specification, which addresses at the structural elements mainly.
+The conceptual model comprises representations of realized concepts, their qualities or attributes, and relationships to other concepts. Most commonly, these are _association_ and _generalisation_ relations. In addition, behaviour can be represented, ranging from the concept level up to the level of the system as a whole. Behavioural aspects, however, fall out of the scope of the current specification, which addresses only the structural elements.
 
 [[sec:uml]]
 === Unified Modelling Language (UML)
 
-The _Unified Modelling Language (UML)_ is a general-purpose, developmental, modelling language in the field of software engineering that is intended to provide a standard way to visualise the design of a system [xref:references.adoc#ref:uml-userguide[uml-userguide]].
+The _Unified Modelling Language (UML)_ is a general-purpose, developmental, computer modelling language in the field of software engineering, that is intended to provide a standard way to visualise the design of a system [xref:references.adoc#ref:uml-userguide[uml-userguide]]. It is a language that facilitates the realization and visualization (diagramming) of a conceptual model, such as the eProcurement conceptual model, which represents the real-world subject matter of public procurement.
 
-This set of specifications is based on the assumption that the conceptual models are represented with UML. Moreover, for the purposes of this convention only the structural elements of UML are considered, and in particular those comprising a class diagram. Next, the most important structural elements are introduced.
+The set of specifications in this documentation is based on the assumption that the conceptual models are represented with UML. Moreover, for the purposes of the convention used, only the structural elements of UML are considered, in particular those comprising a class diagram. The most important structural elements are described below.
 
 A _class_ represents a discrete concept within the domain being modelled. It is a description of a set of individual objects that share the same attributes, behaviour, relationships. Graphically, a class is rendered as a rectangle [xref:references.adoc#ref:uml-userguide[uml-userguide]].