docs: style updates for Lyo 101 setup (#41)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: berezovskyi

docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md

@@ -1,26 +1,26 @@
 # Create an Eclipse Lyo project
 
-This document provides step-by-step instructions for creating a Java project with the necessary configurations to develop any OSLC server/client using Lyo. The instructions assume you are using the Eclipse IDE, but should be equally valid for any other development environment.
+This document provides step-by-step instructions for creating a Java project with the necessary configurations to develop OSLC server/client applications using Lyo. The instructions assume Eclipse IDE is being used, but are equally valid for other development environments.
 
 ## An alternative to the manual steps below
 
 An alternative to the instructions on this page is to use [Lyo Designer](./lyo-designer.md) to quickly generate the project, including a very basic code skeleton. The generated project will also include the necessary setup for OpenApi/Swagger support, TRS, etc.
 
-1. Make sure your environment is set up for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md).
+1. Set up the environment for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md).
 1. Install [Lyo Designer](./install-lyo-designer.md).
 1. Follow the [Create a Modelling Project](./toolchain-modelling-workshop.md#create-modelling-project) instructions (*Only this particular section*) to create the Eclipse project.
-1. Follow the [Adapter Interface](./toolchain-modelling-workshop.md#adaptor-interface-view) instructions (*Only this particular section*) to create a single Adaptor Interface in the model. You do not need to create any additional elements, such as a Service Provider Catalog, Service Provider, etc. Just make sure you set the generation settings as expected.
-1. Follow the [Generate Lyo Java code](./toolchain-modelling-workshop.md#generate-oslc4j-java-code) instructions (*Only this particular section*) to generate your basic project setup.
-1. You are done! But of course, you can proceed with Lyo Designer to model your complete OSLC Server/Client and generate even more of your project code.
+1. Follow the [Adaptor Interface](./toolchain-modelling-workshop.md#adaptor-interface-view) instructions (*Only this particular section*) to create a single Adaptor Interface in the model. Do not create additional elements, such as a Service Provider Catalog, Service Provider, etc. Set the generation settings as expected.
+1. Follow the [Generate Lyo Java code](./toolchain-modelling-workshop.md#generate-oslc4j-java-code) instructions (*Only this particular section*) to generate the basic project setup.
+1. The process is complete! Lyo Designer can be used to model the complete OSLC Server/Client and generate additional project code.
 
 ## Introduction
 
-In the instructions below, we assume the following parameters, which you will need to adjust for your particular project:
+In the instructions below, the following parameters are assumed, which need to be adjusted for the particular project:
 
-* Eclipse Project Name: *adaptor-sample-webapp*
-* Base Package Name for Java Classes: *com.sample.adaptor*
+* Eclipse Project Name: `adaptor-sample-webapp`
+* Base Package Name for Java Classes: `com.sample.adaptor`
 
-We will here only create the code skeleton. The [Toolchain Modelling Workshop](./toolchain-modelling-workshop.md) can then be used to generate the necessary code to become a fully functional server.
+These instructions create only the code skeleton. The [Toolchain Modelling Workshop](./toolchain-modelling-workshop.md) can then be used to generate the necessary code to become a fully functional server.
 
 As a complement when following the instructions below, you can find sample projects under the [Lyo Adaptor Sample Modelling](https://github.com/OSLC/lyo-adaptor-sample-modelling) git repository.
 
@@ -41,41 +41,41 @@ Creating the project consists of these steps:
 
 ## Set up Eclipse
 
-Make sure your environment is set up for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md).
+Set up the environment for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md).
 
 ## Create a Maven project
 
 To create a Maven project from an archetype via Eclipse:
 
-1. Select *File -> New -> Other*.
-1. Then select *Maven Project* under *Maven* group.
-1. Leave the *Create a simple project* checkbox unchecked.
-1. Uncheck the *Use default Workspace location* option and point it to the project root.
-1. Press *Next*.
+1. Select **File -> New -> Other**.
+1. Then select **Maven Project** under **Maven** group.
+1. Leave the **Create a simple project** checkbox unchecked.
+1. Uncheck the **Use default Workspace location** option and point it to the project root.
+1. Press **Next**.
 
 ![](./images/CreateMavenAdaptorProject_Step1.png)
 
 Next, select the `maven-archetype-webapp` archetype:
 
 ![](./images/CreateMavenAdaptorProject_Step2.png)
 
-Next, fill in the **Group Id**, **Artefact Id**, and the **Package Base**.
+Next, fill in the **Group Id**, **Artifact Id**, and the **Package Base**.
 
-* The **Package Base** value (`com.sample.adaptor` on this page) will be used as a base package for your server code.
+* The **Package Base** value (`com.sample.adaptor` on this page) will be used as a base package for the server code.
 
 ![](./images/CreateMavenAdaptorProject_Step3.png)
 
-You should now have the project in Eclipse and the following folder structure:
+The project is now available in Eclipse with the following folder structure:
 
 ![](./images/CreateMavenAdaptorProject_CodeStructure.png)
 
 ## Customise the project POM file
 
-We now need to modify the project *pom.xml* file.
+Modify the project `pom.xml` file.
 
 ### Set up general POM properties
 
-We will also use properties to define a common version for Lyo packages:
+Use properties to define a common version for Lyo packages:
 
 ```xml
 <properties>
@@ -89,9 +89,9 @@ We will also use properties to define a common version for Lyo packages:
 
 ### (Optional) Add Lyo repositories
 
-Lyo release artefacts are on Maven central since 4.0.0 - no action needed from your side.
+Lyo release artefacts are on Maven central since 4.0.0 - no action needed.
 
-If you wish to use the latest development snapshots, you will need the following entry:
+If using the latest development snapshots is required, the following entry is needed:
 
 ```xml
 <repositories>
@@ -111,7 +111,7 @@ If you wish to use the latest development snapshots, you will need the following
 
 ### SLF4J package dependencies
 
-Lyo uses SLF4J for logging, leaving the choice of the actual logging library to use. We will use the simplest option:
+Lyo uses SLF4J for logging, leaving the choice of the actual logging library to use. The simplest option:
 
 ```xml
 <dependency>
@@ -124,7 +124,7 @@ Lyo uses SLF4J for logging, leaving the choice of the actual logging library to
 
 ### Servlet dependencies
 
-We require Java EE 6 or higher and JSTL:
+Java EE 6 or higher and JSTL are required:
 
 ```xml
 <dependency>
@@ -146,7 +146,10 @@ Lyo depends on JAX-RS APIs and your application needs to add implementations of
 
 #### For Lyo 5.x 
 
-For Lyo release 5.0.0 and above, you will need to choose a JAX-RS 2.0 implementation. If you are using Jersey, you should use version 2.35. *Note that starting with Jersey 2.26, HK2 is not bundled with the core artefacts (see the [Jersey migration guide](https://eclipse-ee4j.github.io/jersey.github.io/documentation/2.35/user-guide.html#mig-2.26)).*
+For Lyo release 5.0.0 and above, choose a JAX-RS 2.0 implementation. If using Jersey, use version 2.35. 
+
+!!! note
+    Starting with Jersey 2.26, HK2 is not bundled with the core artefacts (see the [Jersey migration guide](https://eclipse-ee4j.github.io/jersey.github.io/documentation/2.35/user-guide.html#mig-2.26)).
 
 ```xml
 <dependency>
@@ -211,7 +214,7 @@ If your server needs to support OAuth, include the following:
 </dependency>
 ```
 
-To support OAuth, you will need to add the following JAX-RS Providers to your Application (the `javax.ws.rs.core.Application` subclass):
+To support OAuth, add the following JAX-RS Providers to the Application (the `javax.ws.rs.core.Application` subclass):
 
 ```java
 RESOURCE_CLASSES.add(Class.forName("org.eclipse.lyo.server.oauth.webapp.services.ConsumersService"));
@@ -233,14 +236,14 @@ If your OSLC server also needs to consume resources from another server, a depen
 
 ### Configure the Embedded Jetty server for quick debugging
 
-Finally, you should use an embedded servlet container during the debugging to simplify the development process.
+Finally, use an embedded servlet container during the debugging to simplify the development process.
 
 Replace the existing `<build>` entry with the Jetty configuration below, using the following customisations:
 
-* *adaptor-sample* is the context path that can be the same as your eclipse project name (or something more appropriate)
-* *8080* is the port number you want to run the services on.
+* `adaptor-sample` is the context path that can be the same as the eclipse project name (or something more appropriate)
+* `8080` is the port number to run the services on.
 
-This will make your server available under the path http://localhost:8080/adaptor-sample.
+This will make the server available under the path http://localhost:8080/adaptor-sample.
 
 ```xml
 <build>
@@ -273,9 +276,9 @@ This will make your server available under the path http://localhost:8080/adapto
 
 Modify the parameters in `/src/main/webapp/WEB-INF/web.xml` according to the template below.
 
-* *Adaptor Sample* could be the same as your eclipse project name (or something more appropriate).
-* *com.sample.adaptor* should be the same as the base package name for your project.
-* *8080* should match the port number specified in the POM file for Jetty configuration.
+* `Adaptor Sample` could be the same as the eclipse project name (or something more appropriate).
+* `com.sample.adaptor` should be the same as the base package name for the project.
+* `8080` should match the port number specified in the POM file for Jetty configuration.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -317,11 +320,11 @@ The instructions below are based on [Swagger Core JAX RS Project Setup 1.5.X](ht
 
 ### Add OpenApi/Swagger Maven dependencies
 
-Add the following Swagger dependency to your maven pom.xml file.
+Add the following Swagger dependency to the maven pom.xml file.
 
 #### For Lyo 5.0.0 
 
-Assuming you are adopting the Jersey implementation with the version specified above.
+Assuming the Jersey implementation is adopted with the version specified above.
 
 ```xml
 <dependency>
@@ -343,11 +346,11 @@ Assuming you are adopting the Jersey implementation with the version specified a
 </dependency>
 ```
 
-### Co-host Swagger UI with your server 
+### Co-host Swagger UI with the server 
 
-The following steps provide the end-user with an interactive console to the OSLC services, by integrating [Swagger UI](https://swagger.io/swagger-ui/) with your OSLC server.
+The following steps provide the end-user with an interactive console to the OSLC services, by integrating [Swagger UI](https://swagger.io/swagger-ui/) with the OSLC server.
 
-Add the following plugins to the existing `<plugins>` entry of your `pom.xml` file. These plugins download and extract the necessary `Swagger UI` files from [Swagger UI GitHub project](https://github.com/swagger-api/swagger-ui) onto your project:
+Add the following plugins to the existing `<plugins>` entry of the `pom.xml` file. These plugins download and extract the necessary `Swagger UI` files from [Swagger UI GitHub project](https://github.com/swagger-api/swagger-ui) onto the project:
 
 ```xml
 <build>
@@ -419,9 +422,9 @@ public class Application extends javax.ws.rs.core.Application {
 
 ### Configure Swagger's Servlet in the web.xml
 
-Add the following to your web.xml:
+Add the following to the `web.xml`:
 
-* *swagger.api.basepath* depends on your particular settings, as instructed above.
+* `swagger.api.basepath` depends on the particular settings, as instructed above.
 
 ```xml
   <servlet>
@@ -446,7 +449,7 @@ The OpenApi documentation can be achieved with as little as adding `@Api` to eac
 #### `@Api`
 
 1. For each REST service (i.e. OSLC Service), simply add the `@Api` annotation.
-1. (*OPTIONAL*) add the *value* and *description* details. The *value* is used to group the REST methods into common categories, helping in the structuring of the methods in the documentation. You can give it the same value as that of the @Path annotation, collecting all REST methods for the same service together.
+1. (*OPTIONAL*) add the `value` and `description` details. The `value` is used to group the REST methods into common categories, helping in the structuring of the methods in the documentation. You can give it the same value as that of the @Path annotation, collecting all REST methods for the same service together.
 
 ```java
 @Api(value = "requirements", description = "OSLC service for resources of type" + "Requirement")
@@ -464,7 +467,7 @@ For each REST method, add the `@ApiOperation` Swagger annotation.
 !!! example
     If your OSLC Service defines separate Java methods to handle HTML and RDF/XML content types for the same path and HTTP method, OpenApi will only recognise one of these methods and ignore the other.
 
-    **Workaround:** Annotate ALL methods that are identified as unique with the complete list of media types in the *produces* property of the `@ApiOperation` annotation. This way, the generated documentation correctly indicates the existence of all methods.
+    **Workaround:** Annotate ALL methods that are identified as unique with the complete list of media types in the `produces` property of the `@ApiOperation` annotation. This way, the generated documentation correctly indicates the existence of all methods.
 
     ```java
         @GET
@@ -490,7 +493,7 @@ public class Requirement
 
 ### Access the Swagger UI interactive console
 
-Before you can access the [Swagger UI](https://swagger.io/swagger-ui/) interactive console for the first time, edit the `swagger-ui/index.html` file, replacing the url `http://petstore.swagger.io/v2/swagger.json` with the url of your own yaml file `http://localhost:8080/adaptor-sample/services/swagger.yaml`.
+Before accessing the [Swagger UI](https://swagger.io/swagger-ui/) interactive console for the first time, edit the `swagger-ui/index.html` file, replacing the url `http://petstore.swagger.io/v2/swagger.json` with the URL of the YAML file `http://localhost:8080/adaptor-sample/services/swagger.yaml`.
 
 The generated interactive API console can be accessed via:
 
@@ -562,7 +565,7 @@ public class Application extends javax.ws.rs.core.Application {
     }
 ```
 
-Define the `InmemPagedTrsSingleton` singleton class. You will need to complete the code example below, with:
+Define the `InmemPagedTrsSingleton` singleton class. Complete the code example below, with:
 * the code that populates `uris` with the initial set of resources to be managed by `InmemPagedTrs`; 
 * the desired `basePageLimit` and `changelogPageLimit` parameters. 
 
@@ -618,18 +621,16 @@ The application is now ready to respond to REST requests from a TRS Client. Once
 
 ### Update the TRS data set
 
-To update the set of OSLC resources that form the TRS Base and ChangeLog, simply call the following methods in your code:
+To update the set of OSLC resources that form the TRS Base and ChangeLog, call the following methods in the code:
 
 * `InmemPagedTrsSingleton.getInmemPagedTrs().onCreated(aResource);`
 * `InmemPagedTrsSingleton.getInmemPagedTrs().onModified(aResource);`
 * `InmemPagedTrsSingleton.getInmemPagedTrs().onDeleted(aResource.getAbout());`
 
 ## Run the server
 
-Once the server is developed, you can run it by selecting *Run As ➞ Maven build ...* from the project's context menu, and setting the goal to `clean jetty:run-war`.
-
-You can now access your server from http://localhost:8080/adaptor-sample.
+Once the server is developed, run it by selecting **Run As ➞ Maven build ...** from the project's context menu, and setting the goal to `clean jetty:run-war`.
 
-* *adaptor-sample* and *8080* will depend on your particular settings, as instructed above.
+Access the server from [http://localhost:8080/adaptor-sample](http://localhost:8080/adaptor-sample) (`adaptor-sample` and `8080` will depend on the particular settings, as instructed above).
 
-> **Pro Tip:** If you get the error *Project configuration is not up-to-date with pom.xml*, simply right click on the eclipse project and select *Maven ➞ Update Project* ...
+> **Pro Tip:** If the error `Project configuration is not up-to-date with pom.xml` occurs, right click on the eclipse project and select **Maven ➞ Update Project** ...