Merge pull request #146 from tariq1890/minor-doc-improvements

minor documentation improvements

CONTRIBUTING.md

@@ -5,7 +5,7 @@ We welcome contributions. In addition to signing your work as described in
 the section below we ask that the following guidelines be considered when
 opening, reviewing, and merging pull requests.
 
-* No one should merge their own code or code from their own organzation
+* No one should merge their own code or code from their own organization
 * Reviewers should included people from an organization that is not your own
 * If no changes have been requested by other reviewers the (last) reviewer
 merges the pull request on approval

README.md

@@ -4,8 +4,7 @@
 
 ## What is CDI?
 
-CDI (Container Device Interface), is a [specification](SPEC.md), for container-
-runtimes, to support third-party devices.
+CDI (Container Device Interface), is a [specification](SPEC.md), for container-runtimes, to support third-party devices.
 
 It introduces an abstract notion of a device as a resource. Such devices are
 uniquely specified by a fully-qualified name that is constructed from a vendor
@@ -24,7 +23,7 @@ handled by the orchestrator). Because of this focus, the CDI specification is
 simple to implement and allows great flexibility for runtimes and orchestrators.
 
 Note: The CDI model is based on the Container Networking Interface (CNI) model
-and specification.
+and [specification](https://github.com/containernetworking/cni/blob/main/SPEC.md).
 
 ## Why is CDI needed?
 
@@ -35,8 +34,8 @@ more complex, vendors want to perform more operations, such as:
 - Exposing a device to a container can require exposing more than one device
   node, mounting files from the runtime namespace, or hiding procfs entries.
 - Performing compatibility checks between the container and the device (e.g: Can
-  this container run on this device).
-- Performing runtime-specific operations (e.g: VM vs Linux containers-based
+  this container run on this device?).
+- Performing runtime-specific operations (e.g: VM vs Linux container-based
   runtimes).
 - Performing device-specific operations (e.g: scrubbing the memory of a GPU or
   reconfiguring an FPGA).
@@ -46,7 +45,7 @@ write and maintain multiple plugins for different runtimes or even directly
 contribute vendor-specific code in the runtime. Additionally, runtimes don't
 uniformly expose a plugin system (or even expose a plugin system at all) leading
 to duplication of the functionality in higher-level abstractions (such as
-Kubernetes device plugins).
+[Kubernetes device plugins](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/)).
 
 ## How does CDI work?
 
@@ -66,7 +65,7 @@ For CDI to work the following needs to be done:
 ### CRI-O configuration
 
 In CRI-O CDI support is enabled by default. It is configured with the default
-`/etc/cdi, /var/run/cdi` CDI directory locations. Therefore you can start using
+`/etc/cdi, /var/run/cdi` CDI directory locations. Therefore, you can start using
 CDI simply by dropping CDI configuration files in either of those directories,
 static configuration into `/etc/cdi` and dynamically updated one into
 `/var/run/cdi`. If you are unsure of the configured directories you can run this

SPEC.md

@@ -3,8 +3,8 @@
 - [Version](#version)
 - [Overview](#overview)
 - [General considerations](#general-considerations)
-- [CDI JSON Specification](#well-known-error-codes)
-- [CDI CLI Specification](#well-known-error-codes)
+- [CDI JSON Specification](#cdi-json-specification)
+- [Error Handling](#error-handling)
 
 ## Version
 
@@ -72,7 +72,7 @@ For the purposes of this proposal, we define the following terms:
 - _container runtime_ which refers to the higher level component users tend to interact with for managing containers. It may also include lower level components that implement management of containers and pods (sets of containers). e.g: docker, podman, ...
 - _container runtime interface integration_ which refers to a server that implements the Container Runtime Interface (CRI) services, e.g: containerd+cri, cri-o, ...
 
-The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may" and "optional" are used as specified in [RFC 2119][rfc-2119].
+The keywords "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may" and "optional" are used as specified in [RFC 2119][rfc-2119].
 
 [rfc-2119]: https://www.ietf.org/rfc/rfc2119.txt
 
@@ -186,11 +186,11 @@ Note: For a CDI file to be valid, at least one entry must be specified in this a
 
 #### OCI Edits
 
-The `containerEdits` field describes edits to be made to the OCI specification. Currently the following kinds of edits can be made to the OCI specification: `env`, `devices`, `mounts` and `hooks`.
+The `containerEdits` field describes edits to be made to the OCI specification. Currently, the following kinds of edits can be made to the OCI specification: `env`, `devices`, `mounts` and `hooks`.
 
 The `containerEdits` field is referenced in two places in the specification:
   * At the device level, where the edits MUST only be made if the matching device is requested by the container runtime user.
-  * At the container level, where the edits MUST be made if any of the of the device defined in the `devices` field are requested.
+  * At the container level, where the edits MUST be made if any of the device defined in the `devices` field are requested.
 
 
 The `containerEdits` field has the following definition:
@@ -223,11 +223,11 @@ The `containerEdits` field has the following definition:
 
 ## Error Handling
   * Kind requested is not present in any CDI file.
-    Container runtimes should surface an error when a non existent kind is requested.
+    Container runtimes should surface an error when a non-existent kind is requested.
   * Device (not device node) Requested does not exist.
     Container runtimes should surface this error when a non existent device is requested.
   * "Resource" does not exist (e.g: Mount, Hook, ...).
-    Container runtimes should surface this error when a non existent "resource" is requested (e.g: at "run" time).
-    This is because a resource does not need to exist when the spec is written but it needs to exist when the container is created.
+    Container runtimes should surface this error when a non-existent "resource" is requested (e.g: at "run" time).
+    This is because a resource does not need to exist when the spec is written, but it needs to exist when the container is created.
   * Hook fails to execute.
     Container runtimes should surface an error when hooks fails to execute.