Misc. minor corrections, including:

* Unified some formatting.
* removed spurious ```yaml that was being rendered.
* Fixed the definitions for VLANNamespace and IPv4Namespace, which
  were swapped.

docs/concepts/overview.md

@@ -29,9 +29,9 @@ systems.
 
 Wiring Diagram consists of the following resources:
 
-* "Devices": describes any device in the Fabric
+* __Devices__: describes *any* device in the Fabric
     * __Switch__: configuration of the switch, containing for example: port group speeds, port breakouts, switch IP/ASN
-    * __Server__: any physical server attached to the Fabric including Control Nodes
+    * __Server__: *any* physical server attached to the Fabric including Control Nodes
 * __Connection__: *any* logical connection for devices
     * usually it's a connection between two or more ports on two different devices
     * for example: MCLAG Peer Link, Unbundled/MCLAG server connections, Fabric connection between spine and leaf
@@ -41,8 +41,8 @@ Wiring Diagram consists of the following resources:
 ### User-facing API
 
 * VPC API
-    * __VPC__: Virtual Private Cloud, similar to the public cloud VPC it provides an isolated private network for the
-      resources, with support for multiple subnets, each with user-provided VLANs and on-demand DHCP
+    * __VPC__: Virtual Private Cloud, similar a the public cloud VPC, provides an isolated private network for the
+      resources, with support for multiple subnets, each with user-defined VLANs and optional DHCP service
     * __VPCAttachment__: represents a specific VPC subnet assignment to the Connection object which means exact server port to a VPC binding
     * __VPCPeering__: enables VPC-to-VPC connectivity (could be Local where VPCs are used or Remote peering on the border/mixed leaves)
 * External API
@@ -86,15 +86,15 @@ Switch boot and installation.
 * Actual SONiC installers
 * Miscellaneous: rsyslog/ntp
 
-## Fabric
+## Fabric Agent
 
-Control plane and switch agent.
+Control-plane and switch agent.
 
 * Currently Fabric is basically a single controller manager running in Kubernetes
     * It includes controllers for different CRDs and needs
     * For example, auto assigning VNIs to VPCs or generating the Agent configuration
     * Additionally, it's running the admission webhook for Hedgehog's CRD APIs
 * The Agent is watching for the corresponding Agent CRD in Kubernetes API
     * It applies the changes and saves the new configuration locally
-    * It reports some status and information back to the API
+    * It reports status and information back to the API
     * It can perform reinstallation and reboot of SONiC

docs/user-guide/connections.md

@@ -1,18 +1,18 @@
 # Connections
 
-The `Connection` object represents logical and physical connections between any devices in the Fabric (`Switch`,
-`Server` and `External` objects). It's needed to define all connections between the devices in the Wiring Diagram.
+`Connection` objects represent logical and physical connections between the devices in the Fabric (`Switch`,
+`Server` and `External` objects) and are needed to define all the connections in the Wiring Diagram.
 
-All connections referencing some switch and device ports. Only port naming defined by switch profiles can be used in
-the wiring diagram for the switches, NOS (or any other) port names aren't supported. Server ports aren't validated by
+All connections reference switch or server ports. Only port names defined by switch profiles can be used in
+the wiring diagram for the switches. NOS (or any other) port names aren't supported. Currently, server ports aren't validated by
 the Fabric API other than for uniqueness. See the [Switch Profiles and Port Naming](../user-guide/profiles.md) section
 for more details.
 
-There are multiple types of connections.
+There are several types of connections.
 
 ## Server connections (user-facing)
 
-Server connections are used to connect workload servers to the switches.
+Server connections are used to connect workload servers to switches.
 
 ### Unbundled
 
@@ -114,7 +114,7 @@ the Fabric features.
 
 ### Fabric
 
-A Fabric Connections is used between specific spine and leaf, it covers all actual wires between a single pair.
+A Fabric Connection is used between a specific pair of spine and leaf switches, representing all of the wires between them.
 
 ```yaml
 apiVersion: wiring.githedgehog.com/v1alpha2
@@ -225,7 +225,7 @@ Internet, to other networks, or to some other systems such as DHCP, NTP, LMA, or
 
 ### StaticExternal
 
-StaticExternal connections provide a simple way to connect things like DHCP servers directly to the Fabric by connecting
+`StaticExternal` connections provide a simple way to connect things like DHCP servers directly to the Fabric by connecting
 them to specific switch ports.
 
 ```yaml

docs/user-guide/devices.md

@@ -1,15 +1,15 @@
 # Switches and Servers
 
-All devices in the Hedgehog Fabric are divided into two groups: switches and servers, represented by the corresponding
-`Switch` and `Server` objects in the API. These objects are needed to define all participants of the Fabric and their
-roles in the Wiring Diagram as well as [Connections](./connections.md) between them.
+All devices in a Hedgehog Fabric are divided into two groups: switches and servers, represented by the corresponding
+`Switch` and `Server` objects in the API. These objects are needed to define all of the participants of the Fabric and their
+roles in the Wiring Diagram, together with `Connection` objects (see [Connections](./connections.md)).
 
 ## Switches
 
 Switches are the main building blocks of the Fabric. They are represented by `Switch` objects in the API. These objects
 consist of basic metadata like name, description, location, role, as well as port group speeds, port breakouts, ASN,
-IP addresses, and more. Additionally, it contains a reference to the `SwitchProfile` object that defines the switch
-model and capabilities, more details can be found in the [Switch Profiles and Port Naming](./profiles.md) section.
+IP addresses, and more. Additionally, a `Switch` contains a reference to a `SwitchProfile` object that defines the switch
+model and capabilities. More details can be found in the [Switch Profiles and Port Naming](./profiles.md) section.
 
 ```yaml
 apiVersion: wiring.githedgehog.com/v1alpha2
@@ -39,7 +39,7 @@ spec:
   vlanNamespaces: # Defines which VLANs could be used to attach servers
   - default
   vtepIP: 172.30.12.100/32
-  groups: # Defines which groups the switch belongs to
+  groups: # Defines which groups the switch belongs to, by referring to SwitchGroup objects
   - some-group
   redundancy: # Optional field to define that switch belongs to the redundancy group
     group: eslag-1 # Name of the redundancy group
@@ -63,7 +63,7 @@ Redundancy groups are used to define the redundancy between switches. It's a reg
 switches and currently it could be MCLAG or ESLAG (EVPN MH / ESI). A switch can only belong to a single redundancy
 group.
 
-MCLAG is only supported for pair of switches and ESLAG is supported for up to 4 switches. Multiple types of redundancy
+MCLAG is only supported for pairs of switches and ESLAG is supported for up to 4 switches. Multiple types of redundancy
 groups can be used in the fabric simultaneously.
 
 Connections with types `mclag` and `eslag` are used to define the servers connections to switches. They are only

docs/user-guide/vpcs.md

@@ -2,8 +2,8 @@
 
 ## VPC
 
-A Virtual Private Cloud (VPC) is similar to a public cloud VPC. It provides an isolated private network for the
-resources with support for multiple subnets, each with user-provided VLANs and on-demand DHCP.
+A Virtual Private Cloud (VPC) is similar to a public cloud VPC. It provides an isolated private network with support for multiple subnets,
+each with user-defined VLANs and optional DHCP services.
 
 ```yaml
 apiVersion: vpc.githedgehog.com/v1alpha2
@@ -12,8 +12,8 @@ metadata:
   name: vpc-1
   namespace: default
 spec:
-  ipv4Namespace: default # Limits to which subnets could be used by VPC to guarantee non-overlapping IPv4 ranges
-  vlanNamespace: default # Limits to which switches VPC could be attached to guarantee non-overlapping VLANs
+  ipv4Namespace: default # Limits what subnets can the VPC use to guarantee non-overlapping IPv4 ranges
+  vlanNamespace: default # Limits what Vlan Ids can the VPC use to guarantee non-overlapping VLANs
 
   defaultIsolated: true # Sets default behavior for the current VPC subnets to be isolated
   defaultRestricted: true # Sets default behavior for the current VPC subnets to be restricted
@@ -48,8 +48,8 @@ spec:
       subnet: 10.10.100.0/24
       vlan: 1100
 
-  permit: # Defines which subnets of the current VPC could communicate to each other, applied on top of subnets "isolated" flag (doesn't affect VPC peering)
-    - [subnet-1, subnet-2, subnet-3] # 1, 2 and 3 subnets could communicate to each other
+  permit: # Defines which subnets of the current VPC can communicate to each other, applied on top of subnets "isolated" flag (doesn't affect VPC peering)
+    - [subnet-1, subnet-2, subnet-3] # 1, 2 and 3 subnets can communicate to each other
     - [subnet-4, subnet-5] # Possible to define multiple lists
 
   staticRoutes: # Optional, static routes to be added to the VPC
@@ -68,11 +68,11 @@ allowed by permit lists.
 
 _Restricted subnet_ means that all hosts in the subnet are isolated from each other within the subnet.
 
-A Permit list is defined as a list of subnets that could communicate with each other.
+A Permit list contains a list. Every element of the list is a set of subnets that can communicate with each other.
 
-### Third-party DHCP server
+### Third-party DHCP server configuration
 
-In case you use a third-party DHCP server by configuring `spec.subnets.<subnet>.dhcp.relay`, additional information is
+In case you use a third-party DHCP server, by configuring `spec.subnets.<subnet>.dhcp.relay`, additional information is
 added to the DHCP packet forwarded to the DHCP server to make it possible to identify the VPC and subnet. This
 information is added under the RelayAgentInfo (option 82) in the DHCP packet. The relay sets two suboptions in the
 packet:
@@ -98,7 +98,7 @@ metadata:
 spec:
   connection: server-1--mclag--s5248-01--s5248-02 # Connection name representing the server port(s)
   subnet: vpc-1/default # VPC subnet name
-  nativeVLAN: true # Optional, if true the port will be configured as a native VLAN port (untagged)
+  nativeVLAN: true # (Optional) if true, the port will be configured as a native VLAN port (untagged)
 ```
 
 ## VPCPeering
@@ -108,7 +108,7 @@ A VPCPeering enables VPC-to-VPC connectivity. There are two types of VPC peering
 * Local: peering is implemented on the same switches where VPCs are attached
 * Remote: peering is implemented on the border/mixed leaves defined by the `SwitchGroup` object
 
-VPC peering is only possible between VPCs attached to the same IPv4 namespace.
+VPC peering is only possible between VPCs attached to the same IPv4 namespace (see [IPv4Namespace](#ipv4namespace))
 
 ### Local VPC peering
 
@@ -144,7 +144,6 @@ spec:
 It's possible to specify which specific subnets of the peering VPCs could communicate to each other using the `permit`
 field.
 
-```yaml
 ```yaml
 apiVersion: vpc.githedgehog.com/v1alpha2
 kind: VPCPeering
@@ -165,8 +164,8 @@ spec:
 
 ## IPv4Namespace
 
-An IPv4Namespace defines non-overlapping VLAN ranges for attaching servers. Each switch belongs to a list of VLAN
-namespaces with non-overlapping VLAN ranges.
+An `IPv4Namespace` defines a set of (non-overlapping) IPv4 address ranges available for use by VPC subnets.
+Each VPC belongs to a specific IPv4 namespace. Therefore, its subnet prefixes must be from that IPv4 namespace.
 
 ```yaml
 apiVersion: vpc.githedgehog.com/v1alpha2
@@ -181,11 +180,12 @@ spec:
 
 ## VLANNamespace
 
-A VLANNamespace defines non-overlapping IPv4 ranges for VPC subnets. Each VPC belongs to a specific IPv4 namespace.
+A `VLANNamespace` defines a set of VLAN ranges available for attaching servers to switches. Each switch can belong to one or more
+disjoint VLANNamespaces.
 
 ```yaml
 apiVersion: wiring.githedgehog.com/v1alpha2
-kind: VLANNamespace
+kind: VLANNamespac`
 metadata:
   name: default
   namespace: default