fix(documentation): rephrase part of the library documentation

tmorin · Dec 5, 2020 · 3b7e6e6 · 3b7e6e6
1 parent f8bca30
commit 3b7e6e6
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 34 deletions.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ This repository hosts a [PlantUML] lib which provides several `packages`.
 Each package focus on a particular technology/approach: Amazon Web Services (AWS), Azure, C4 Model or even EventStorming and more.
 
 The repository hosts also two command lines utilities.
-The first one (`glib`) helps to generate packages, the second one (`gdiag`) helps to use the packages within external projects in order to bootstrap a local and generate diagrams.
+The first one (`glib`) helps to generate packages, the second one (`gdiag`) helps to use the packages from external projects in order.
 
 ## Contributing
 
@@ -42,7 +42,7 @@ The available packages:
 
 ## Usage
 
-The library can directly be used remotely hitting the GitHub repository.
+The library can be directly used remotely hitting the GitHub repository.
 
 However, the performances are not good enough for intensive usage.
 In this case, the library should be installed locally and use directly from the file system.
@@ -51,11 +51,10 @@ To help the local installation, an NPM package is available.
 
 ## Usage of the NPM package
 
-A npm package [@tmorin/plantuml-libs](https://www.npmjs.com/package/@tmorin/plantuml-libs) is available.
-Its purpose is to provide locally the libraries as well as the command-line utility: `gdiag`.
-The command-line utility managed it-self the download of the PlantUML jar.
+The NPM package [@tmorin/plantuml-libs](https://www.npmjs.com/package/@tmorin/plantuml-libs) provides the CLI commands as well as the packages
+The CLI commands managed them-self the download of the PlantUML jar.
 
-Install the package globally:
+Install the NPM package globally:
 ```shell script
 npm i -g @tmorin/plantuml-libs
 ```

diff --git a/dist/README.md b/dist/README.md
@@ -41,22 +41,25 @@ Include locally the library:
 
 ## include vs !include
 
-When documenting large projects, it often a good practice to define the components in separate `.puml` files which are then included in others containing the diagrams to render.
-So that, the definition of the components can be re-used over the diagram.
-Moreover, the diagrams which include them are automatically updated.
+When documenting large projects, it's often a good practice to define the components in separate `.puml` files which will be then included in other `.puml` files containing the diagrams to render.
+So that, the component definitions can be re-used among the diagrams.
 
-However, be careful about relative and absolute paths with `!include` vs `include()`.
-According to where you are (separate files vs diagram files), the _relative paths_ won't be resolve from the _current directory_.
+However, be careful about relative and absolute paths with the usage of `!include` (the native PlantUML directive) vs `include()` (a custom procedure provided in this library).
+According to where you are (i.e. reference files vs diagram files), the _relative paths_ won't be resolved from the _current directory_.
 
 Given the following file tree, the following snippets should help you to configure files properly.
 
 - project/
-- project/reference/c4.puml
-- project/reference/aws.puml
-- project/src/guidebook/component/c4.puml
-- project/src/guidebook/component/aws.puml
-
-### project/reference/c4.puml
+  - ref/
+    - c4.puml
+    - aws.puml
+  - src/
+    - guidebook/
+      - component/
+        - c4.puml
+        - aws.puml
+
+### project/ref/c4.puml
 ```plantuml
 !global $INCLUSION_MODE="local"
 !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist"
@@ -66,7 +69,7 @@ include('c4model/bootstrap')
 ' .....
 ```
 
-### project/reference/aws.puml
+### project/ref/aws.puml
 ```plantuml
 !global $INCLUSION_MODE="local"
 !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist"
@@ -79,7 +82,7 @@ include('aws-20200911/bootstrap')
 ### project/src/guidebook/component/c4.puml
 ```plantuml
 @startuml level1-system
-!include ../../../references/c4.puml
+!include ../../../ref/c4.puml
 !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/"
 !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION
 ' description of the diagram below
@@ -90,7 +93,7 @@ include('aws-20200911/bootstrap')
 ### project/src/guidebook/component/aws.puml
 ```plantuml
 @startuml infrastructure-production
-!include ../../../references/aws.puml
+!include ../../../ref/aws.puml
 !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/"
 !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION
 ' description of the diagram below

diff --git a/lib/glib/template/library.md b/lib/glib/template/library.md
@@ -34,22 +34,25 @@ Include locally the library:
 
 ## include vs !include
 
-When documenting large projects, it often a good practice to define the components in separate `.puml` files which are then included in others containing the diagrams to render.
-So that, the definition of the components can be re-used over the diagram.
-Moreover, the diagrams which include them are automatically updated.
+When documenting large projects, it's often a good practice to define the components in separate `.puml` files which will be then included in other `.puml` files containing the diagrams to render.
+So that, the component definitions can be re-used among the diagrams.
 
-However, be careful about relative and absolute paths with `!include` vs `include()`.
-According to where you are (separate files vs diagram files), the _relative paths_ won't be resolve from the _current directory_.
+However, be careful about relative and absolute paths with the usage of `!include` (the native PlantUML directive) vs `include()` (a custom procedure provided in this library).
+According to where you are (i.e. reference files vs diagram files), the _relative paths_ won't be resolved from the _current directory_.
 
 Given the following file tree, the following snippets should help you to configure files properly.
 
 - project/
-- project/reference/c4.puml
-- project/reference/aws.puml
-- project/src/guidebook/component/c4.puml
-- project/src/guidebook/component/aws.puml
-
-### project/reference/c4.puml
+  - ref/
+    - c4.puml
+    - aws.puml
+  - src/
+    - guidebook/
+      - component/
+        - c4.puml
+        - aws.puml
+
+### project/ref/c4.puml
 ```plantuml
 !global $INCLUSION_MODE="local"
 !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist"
@@ -59,7 +62,7 @@ include('c4model/bootstrap')
 ' .....
 ```
 
-### project/reference/aws.puml
+### project/ref/aws.puml
 ```plantuml
 !global $INCLUSION_MODE="local"
 !global $LIB_BASE_LOCATION="../node_modules/@tmorin/plantuml-libs/dist"
@@ -72,7 +75,7 @@ include('aws-20200911/bootstrap')
 ### project/src/guidebook/component/c4.puml
 ```plantuml
 @startuml level1-system
-!include ../../../references/c4.puml
+!include ../../../ref/c4.puml
 !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/"
 !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION
 ' description of the diagram below
@@ -83,7 +86,7 @@ include('aws-20200911/bootstrap')
 ### project/src/guidebook/component/aws.puml
 ```plantuml
 @startuml infrastructure-production
-!include ../../../references/aws.puml
+!include ../../../ref/aws.puml
 !global $IMAGE_BASE_PATH="../../" + $LIB_BASE_LOCATION + "/"
 !global $LIB_BASE_LOCATION="../../" + $LIB_BASE_LOCATION
 ' description of the diagram below