update documentation, update vale rules, reduce warnings and suggestions made by vale

Signed-off-by: Karel van Klink <karel.vanklink@geant.org>

docs/architecture/dtap/production.md

-# Production environment
+# Production environment
\ No newline at end of file
+
+TBA

docs/architecture/dtap/test.md

 # Test environment
+
+TBA

docs/architecture/index.md

@@ -4,30 +4,40 @@ An overview of the architecture of GAP is depicted in the following picture:
 
 ![](../assets/images/Architecture-WFO_Geant_specific.drawio.png)
 
-The diagram, shows how GAP position itself as a single point of access not only for the interaction with a specific technical domain, in our case the IP/MPLS network, but also for the interaction with OSS/BSS systems that are authoritative for certain types of resources.
+The diagram visualises how GAP positions itself as a single point of access, not only for the interaction with a
+specific technical domain. In our case with the IP/MPLS network, it also models the interaction with OSS/BSS systems
+that are authoritative for certain types of resources.
 
-GAP is responsible not only to allocate and release these resources but also to verify that all the systems are in sync over time.
+GAP is responsible not only for allocation and release of these resources, but also for verification whether all systems
+are in sync over time.
 
-In other words, operators are no longer responsible to prepare resources before doing changes (for example allocating IP networks or addresses and configuring accordingly DNS): the GAP component responsible for the interaction with that particular system will take care of allocating and configure the necessary resources.
+In other words, operators are no longer responsible for preparation of resources before performing changes (for example
+allocating IP networks or addresses, and configuring DNS accordingly). The GAP component responsible for the interaction
+with that particular system will take care of allocating and configuring the necessary resources.
 
-Included in the orchestration layer, there is a service database that stores all the instances of the services in accordance to the domain models. More details are available in the section [GAP components](../architecture/components/index.md)
+Included in the orchestration layer there is a service database that stores all instances of the services in accordance
+to their respective domain models. More details are available in the section
+[GAP components](../architecture/components/index.md)
 
 ## OSS/BSS systems currently in scope
 
 ### Infoblox
 
-Infoblox is the GÉANT DDI (DHCP/DNS/IPAM) platform and it is responsible to manage the allocation of IP networks and addresses (both IPv4 and IPv6) as well as the assignment of domain names for the zones GÉANT is authoritative for.
+Infoblox is the GÉANT DDI (DHCP/DNS/IPAM) platform responsible for managing the allocation of IP networks and
+addresses (both IPv4 and IPv6). It also assigns domain names in the zones that GÉANT is authoritative over.
 
-Currently GAP support:
+Currently, GAP supports:
 
 - Allocation and deletion of an IP (v4/v6) Network within an existing network container
-- Allocation and deletion of a host and relative IPv4 and IPv6 addresses including A,AAAA and PTR records.
+- Allocation and deletion of a host and relative IPv4 and IPv6 addresses including `A`, `AAAA`, and `PTR` records
 
-More detailed information about this integration is available in the [Ipam integration module](../admin_guide/oss_bss/ipam.md)
+More detailed information about this integration is available in the
+[IPAM integration module](../admin_guide/oss_bss/ipam.md).
 
 ### Netbox
 
-Netbox is responsible of managing physical resources such as nodes and interfaces. More specifically, it contains all the routers and the interfaces and provides to WFO the list of free interfaces.
+Netbox is responsible for managing physical resources such as nodes and interfaces. More specifically, it contains all
+the routers and their interfaces, and provides to WFO which of these interfaces are available for use.
 
 An interface can be in 3 different states:
 
@@ -35,21 +45,28 @@ An interface can be in 3 different states:
 - __reserved__: currently in use by a workflow that is still running
 - __in use__: holding a service currently active
 
-More detailed information about this integration is available in the [Physical resources integration module](../admin_guide/oss_bss/netbox.md)
+More detailed information about this integration is available in the
+[Physical resources integration module](../admin_guide/oss_bss/netbox.md)
 
 ### LibreNMS
 
-LibreNMS is a general purpose monitoring system in use at GÉANT to gather relevant metrics as well as checks and facts. LibreNMS is also the inventory for Oxidized: a network configuration backup system that is used to have versioned configuration backups of routers, switches and any other network device that is supported.
+LibreNMS is a general purpose monitoring system in use at GÉANT to gather relevant metrics, checks, and facts.
+LibreNMS is also the inventory for Oxidized: a network configuration backup system. It is used to have versioned
+configuration backups of routers, switches, and any other network devices that are supported.
+
+More detailed information about this integration is available in the
+[LibreNMS integration module](../admin_guide/oss_bss/librenms.md).
 
-More detailed information about this integration is available in the [LibreNMS integration module](../admin_guide/oss_bss/librenms.md)
 ### Kentik (planned)
 
-Kentik is a Network Observability tool and it collects several information from our PE routers. For this reason it is not in scope for PHASE1.
+Kentik is a Network Observability tool which collects various data points from deployed PE routers.
+For this reason it is not in scope for PHASE1.
 
-### Inventory Provider (planned)
+### Inventory provider (planned)
 
-At the time of writing, Inventory provider gets the list of the routers from network engineering SOT servers. This will change and Inventory provider can directly query coreDB.
+At the time of writing, the Inventory Provider gets the list of routers from the network engineering SOT servers.
+This will change and Inventory Provider is then able to directly query CoreDB.
 
 ## Interaction with a technical domain: IP/MPLS
 
-GAP
+TBA
\ No newline at end of file

docs/assets/images/image_sources/Architecture.drawio

@@ -359,7 +359,7 @@
         <mxCell id="fU0Jv1-IXl80mrmCQJBs-2" value="LSO&lt;br&gt;Lightweight Service Orchestrator" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontFamily=Tahoma;" parent="1" vertex="1">
           <mxGeometry x="12.5" y="550" width="245" height="40" as="geometry" />
         </mxCell>
-        <mxCell id="fU0Jv1-IXl80mrmCQJBs-11" value="OSS/BSS Already in use in Geant" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
+        <mxCell id="fU0Jv1-IXl80mrmCQJBs-11" value="OSS/BSS Already in use in GÉANT" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
           <mxGeometry x="900" y="450" width="70" height="70" as="geometry" />
         </mxCell>
         <mxCell id="fU0Jv1-IXl80mrmCQJBs-12" value="" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;dashed=1;" parent="1" vertex="1">

docs/index.md

@@ -5,39 +5,45 @@ The focus of this platform is configuration management and service orchestration
 
 ## What is GAP
 
-GAP represents the vision of GÉANT in terms of Network Automation and Orchestration and it summarise few years of experiments and initiatives in this field with the aim of fulfilling the following objectives:
+GAP represents the vision of GÉANT in terms of Network Automation and Orchestration. It summarises a few years of
+experimenting and initiatives in this field, with the aim of fulfilling the following objectives:
 
-- to have a simple interface for managing network service lifecycle (provisioning, deprovisioning, modification) that ensures that the correct configuration is pushed on the network
-- to have a platform - not a single product - that is capable of adapt and evolve according to GÉANT needs
-- to have certainty that OSS/BSS systems are in sync with the actual configuration running in the network
-- to introduce a different way of working that avoids fragmentation and silos.
+- To have a simple interface for managing the network service lifecycle (provisioning, termination, modification)
+that ensures that the correct configuration is pushed onto the network
+- To have a platform - not a single product - that is capable of adapting and evolving, according to GÉANT needs
+- To have certainty that OSS/BSS systems are in sync with the actual configuration deployed in the network
+- To introduce a different way of working that avoids fragmentation and silos
 
-GAP is partially based on Open Source Software and partially internally developed and integrates with most of the tooling already in use in GÉANT.
+GAP is part based on Open Source Software, and part internally developed. GAP integrates with most of the tooling
+already in use in GÉANT.
 
 !!! Credits
 
     The OSS components that GAP uses are mainly:
 
-    - Workflow Orchestrator [https://workfloworchestrator.org/](https://workfloworchestrator.org/) (developed and maintained by [Surf](https://www.surf.nl/) and [ESnet](https://www.es.net/))
+    - Workflow Orchestrator [https://workfloworchestrator.org/](https://workfloworchestrator.org/) (developed and maintained by [SURF](https://www.surf.nl/) and [ESnet](https://www.es.net/))
     - Ansible [https://www.ansible.com/](https://www.ansible.com/)
 
 More information about the GAP architecture is available in the [Architecture](./architecture/index.md) section.
 
-
-
 ## About this documentation portal
 
 This site is organized in 4 main sections:
 
-- [Architecture](./architecture/index.md): covers the architecture of GAP including all the components and the interactions between them
-- [Legacy GAP](./legacy_platform/overview.md): provides operational guides of the legacy GAP platform based on Ansible and Jenkins
-- [Admin guide](./admin_guide/index.md): covers the detail information of the domain models in WFO, the description of the workflows and all the Ansible mechanics
+- [Architecture](./architecture/index.md): covers the architecture of GAP including all the components and the
+interactions between them
+- [Legacy GAP](./legacy_platform/overview.md): provides operational guides of the legacy GAP platform based on Ansible
+and Jenkins
+- [Admin guide](./admin_guide/index.md): covers the detail information of the domain models in WFO, descriptions of the
+workflows, and all the Ansible mechanics
 - [User guide](./user_guide/index.md): provides operational guides of the Workflow Orchestrator based GAP
 
-The documentation provided in this portal is final and reviewed. For information about the ongoing work please refer to the wiki [GOAT Wiki](https://wiki.geant.org/display/NNAT/GOAT+-+Geant+Orchestration+and+Automation+Team)
+The documentation provided in this portal is final and reviewed. For information about the ongoing work please refer to
+the [internal wiki page](https://wiki.geant.org/display/NNAT/GOAT+-+Geant+Orchestration+and+Automation+Team).
 
-Also this documentation does not cover the design of network services, just the modelling and the mechanics related with automation.
+Also, this documentation does not cover the design of network services, just the modelling and the mechanics related to
+automation.
 
 !!! Info
 
-    For any info or clarification you can refer to goat_at_geant_dot_org
+    For any info or clarification you can refer to `goat`@`geant.org`.

docs/user_guide/routers/deploy_router.md

@@ -2,7 +2,7 @@
 
 From a bird's-eye view, the process of deploying a new router in the network is as follows:
 
-1. Manually configure the router such that it's reachable from out-of-band (OOB).
+1. Manually configure the router such that it is reachable from out-of-band (OOB).
 2. Upgrade the router to the most recent OS.
 3. Deploy base configuration.
 4. Configure trunks to connect the router to the network.

includes/glossary.md

 *[AAA]: Authentication, Authorisation, Accounting
 *[BGP]: Border Gateway Protocol
+*[BSS]: Business Support Systems
 *[CFS]: Customer Facing Service
+*[DCIM]: Datacenter Infrastructure Manager
+*[DHCP]: Dynamic Host Configuration Protocol
+*[DNS]: Domain Name System
+*[DTAP]: Development, Testing, Acceptance, and Production
 *[eBGP]: External BGP
 *[GA]: Access Port
 *[GAN]: Access Node
 *[GAP]: GÉANT Automation Platform
 *[GP]: Physical Port
+*[GUI]: Graphical User Interface
 *[iBGP]: Internal BGP
+*[IGP]: Internal Gateway Protocol
 *[IFS]: Interface Facing Service
+*[IPAM]: IP Address Management
 *[IS-IS]: Intermediate System to Intermediate System
 *[L3VPN]: Layer 3 VPN
 *[MPLS]: Multi-Protocol Label Switching
@@ -15,7 +23,11 @@
 *[MTU]: Maximum Transmission Unit
 *[NREN]: National Research and Education Network
 *[OOB]: Out-of-band
+*[OSS]: Operational Support Systems
 *[PoP]: Point of Presence
 *[RFC]: Request For Comments
 *[SDP]: Service Delivery Point
+*[SNMP]: Simple Network Management Protocol
+*[SOT]: Source Of Truth
+*[TBA]: To be added
 *[WFO]: Workflow Orchestrator

mkdocs.yml

@@ -68,12 +68,12 @@ nav:
   - Admin Guide:
     - admin_guide/index.md
     - Ansible:
-        - admin_guide/Ansible/ansible.md
+        - admin_guide/ansible/ansible.md
     - WFO:
-        - Diagram: admin_guide/WFO/overview.md
-        - Sites: admin_guide/WFO/sites.md
-        - Routers: admin_guide/WFO/routers.md
-        - Iptrunks: admin_guide/WFO/iptrunks.md
+        - Diagram: admin_guide/wfo/overview.md
+        - Sites: admin_guide/wfo/sites.md
+        - Routers: admin_guide/wfo/routers.md
+        - Iptrunks: admin_guide/wfo/iptrunks.md
     - OSS/BSS integration:
         - Infoblox: admin_guide/oss_bss/ipam.md
         - Netbox: admin_guide/oss_bss/netbox.md

vale/.vale.ini

@@ -2,9 +2,9 @@ StylesPath = styles
 
 MinAlertLevel = suggestion
 
-Vocab = geant-jargon, Sphinx
+Vocab = geant-jargon
 
-Packages = proselint, Microsoft
+Packages = proselint, Microsoft, custom
 
 [*.md]
 BasedOnStyles = Vale, proselint, Microsoft
@@ -15,5 +15,6 @@ Microsoft.Passive = NO
 Microsoft.GeneralURL = NO
 ; Replacing a ... with … shouldn't be holding back the entire CI pipeline
 proselint.Typography = warning
-; Same applies for not using contractions
-Microsoft.Contractions = warning
+; Same applies for not using contractions, the custom package actually lints in the opposite direction
+Microsoft.Contractions = NO
+custom.contractions = YES

vale/styles/Vocab/Sphinx/accept.txt

-toctree

vale/styles/Vocab/geant-jargon/accept.txt

-Linecard
-APIs
-IP/MPLS
-IPAM
-MPLS
-MTTR
-configuration as code
-[Rr]eachability
-[Ll]oopback
+AAA
+according(ly)?
+address
 Ansible
+APIs?
 [Bb]ackbone
-IFS
+BGP
+BSS
 CFS
+configuration as code
+components?
+contains?
+DCIM
+DDI
+DHCP
+DNS
+DTAP
+FXP
 GAN
-SDP
-AAA
-GÉANT Automation Platform
 GAP
+GÉANT Automation Platform
+IFS
+IGP
+Infoblox
+IP( address)?
+IPAM
+iptrunk_*
+IP/MPLS
+ISIS
+Junos
+Kentik
+(LAG|lag)
+LibreNMS
+Linecard
+LLDP
+[Ll]oopback
+[Mm]odify
+MPLS
+MTTR
+MTU
 [Mm]ultipoint
-WFO
-BGP
-FXP
+Netbox
 NREN
-MTU
 OOB
-Junos
-IP[Tt]runk
-IP[Tt]runks
-Netbox
-iptrunk_*
-geant_s_sid
-deprovisioning
-[Uu]ndeployment
-Infoblox
-Ipam
-Kentik
+[Rr]eachability
+SDP
+SID
+SOT
+SNMP
+TBA
+VLAN
+WFO
+Workflow Orchestrator

vale/styles/custom/Contractions.yml

+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: suggestion
+ignorecase: true
+swap:
+  aren't: are not
+  can't: cannot
+  couldn't: could not
+  didn't: did not
+  don't: do not
+  doesn't: does not
+  hasn't: has not
+  haven't: have not
+  how's: how is
+  isn't: is not
+  it's: it is
+  shouldn't: should not
+  that's: that is
+  they're: they are
+  wasn't: was not
+  we're: we are
+  we've: we have
+  weren't: were not
+  what's: what is
+  when's: when is
+  where's: where is
+  won't: will not