From 43d4892382b5101a82920372f4c4836881c0671f Mon Sep 17 00:00:00 2001
From: jc-berger <>
Date: Tue, 13 Apr 2021 15:04:46 -0400
Subject: [PATCH 1/5] made docs adhere to style guide

---
 .../assembly_migrating-to-devfile-v2.adoc     |  9 +++--
 .../partials/proc_adding-event-bindings.adoc  |  9 ++---
 .../partials/proc_migrating-commands.adoc     | 24 +++++-------
 .../partials/proc_migrating-components.adoc   | 37 ++++++-------------
 .../partials/proc_migrating-plug-ins.adoc     | 16 ++++----
 .../partials/proc_migrating-projects.adoc     |  9 +++--
 .../proc_migrating-schema-version.adoc        |  7 ++--
 ...ring-to-a-parent-devfile-in-a-devfile.adoc | 15 ++++++--
 8 files changed, 57 insertions(+), 69 deletions(-)

diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
index 00ff2030..f9199e70 100644
--- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
+++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
@@ -11,7 +11,7 @@ endif::[]
 
 :context: assembly_migrating-to-devfile-v2
 
-This guide explains how to migrate an existing v1.0 devfile to v2.0.
+The following documents explain how to migrate an existing devfile v1.x to a devfile v2.x:
 
 * xref:migrating-schema-version.adoc[]
 * xref:migrating-projects.adoc[]
@@ -24,10 +24,11 @@ This guide explains how to migrate an existing v1.0 devfile to v2.0.
 [role="_additional-resources"]
 .Additional resources
 
-* New metadata: `version`. See link:https://github.com/che-incubator/devworkspace-api/issues/10[corresponding issue].
-* New mandatory metadata for plugins. See link:https://github.com/devfile/api/issues/31[corresponding issue].
+For a deeper understand of migrating devfiles, go to the following GitHub issues:
+
+* link:https://github.com/devfile/api/issues/10[Devfile schema]
+* link:https://github.com/devfile/api/issues/31[Plug-in mechanism]
 
 
 ifdef::parent-context-of-assembly_migrating-to-devfile-v2[:context: {parent-context-of-assembly_migrating-to-devfile-v2}]
 ifndef::parent-context-of-assembly_migrating-to-devfile-v2[:!context:]
-
diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
index a013f442..b37faef2 100644
--- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
+++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
@@ -2,11 +2,7 @@
 = Adding event bindings
 
 [role="_abstract"]
-Commands can be bound to events to form four different types of events: `preStart`, `postStart`, `preStop`, and `postStop`.
-
-.Prerequisites
-
-
+This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x.
 
 .Procedure
 
@@ -46,4 +42,5 @@ events:
 
 [role="_additional-resources"]
 .Additional resources
-* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue].
+
+For a deeper understand of adding event bindings, go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[lifecycle bindings to bind commands].
diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
index 6485d215..a8d60b07 100644
--- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
@@ -2,7 +2,7 @@
 = Migrating commands
 
 [role="_abstract"]
-This section describes how to migrate the `commands` section to devfile v2.x. A command specified in a v1.0 devfile does not work as it is in a devfile v2.x.
+This section describes how to migrate the `commands` section to devfiles v2.x. A command specified in a devfile v1.x does not work in a devfile v2.x.
 
 .Procedure
 
@@ -18,17 +18,13 @@ This section describes how to migrate the `commands` section to devfile v2.x. A
 [role="_additional-resources"]
 .Additional resources
 
-* Command groups: build, run, test, debug. See https://github.com/che-incubator/devworkspace-api/issues/27[corresponding issue].
-* Apply Command. See https://github.com/devfile/api/issues/56[corresponding issue].
+For a deeper understanding of migrating commands, go to the following GitHub issues:
 
-* Environment variables for a specific command. See https://github.com/che-incubator/devworkspace-api/issues/21[corresponding issue].
-
-* Renaming workdir into workingDir. See https://github.com/che-incubator/devworkspace-api/issues/22[corresponding issue].
-
-* Id and label for composite commands. See https://github.com/che-incubator/devworkspace-api/issues/18[corresponding issue].
-
-* Run exec commands as specific user. See https://github.com/che-incubator/devworkspace-api/issues/34[corresponding issue].
-
-* Devfile metadata: add a link to an external website. See https://github.com/che-incubator/devworkspace-api/issues/38[corresponding issue].
-
-* Stack and devfile matching rules. See https://github.com/che-incubator/devworkspace-api/issues/40[corresponding issue].
+* link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug]
+* link:https://github.com/devfile/api/issues/56[Apply command]
+* link:https://github.com/devfile/api/issues/21[Environment variables for a specific command]
+* link:https://github.com/devfile/api/issues/22[Renaming workdir into workingDir]
+* link:https://github.com/devfile/api/issues/18[Id and label for composite commands]
+* link:https://github.com/devfile/api/issues/34[Run exec commands as specific user]
+* link:https://github.com/devfile/api/issues/38[Devfile metadata: add a link to an external website]
+* link:https://github.com/devfile/api/issues/40[Stack or devfile matching rules]
diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc
index fc886947..f2eba500 100644
--- a/docs/modules/user-guide/partials/proc_migrating-components.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc
@@ -2,13 +2,13 @@
 = Migrating components
 
 [role="_abstract"]
-This section describes how to migrate components to devfile v2. There ARE major changes in the `components` section of the devfile. A component specified in a v1.0 devfile will NOT work as it is in a devfile v2.0.
+This section describes how to migrate components to devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x
 
 .Procedure
 
 . Component is a polymorphic type
 +
-For a better syntax validation component now is defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
+For a better syntax, the validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
 +
 [source,yaml]
 ----
@@ -26,32 +26,17 @@ components:
        uri: https://.../mongo.yaml
 ----
 +
-See https://github.com/devfile/api/issues/4[corresponding issue].
-
-. Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue].
-
-. Out of Main Pod Components. See  https://github.com/devfile/api/issues/48[corresponding issue].
-
-. Replace Alias with Name. See  https://github.com/devfile/api/issues/9[corresponding issue].
-
-. Renaming dockerimage component type. See  https://github.com/devfile/api/issues/8[corresponding issue].
-
-. Specify sources path for containers. See  https://github.com/devfile/api/issues/17[corresponding issue].
-
-. Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue].
-
-. Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/33[corresponding issue].
-
 
 [role="_additional-resources"]
 .Additional resources
 
+For a deeper understanding of migrating components, go to the following GitHub issues:
 
-* Component is a polymorphic type. See https://github.com/devfile/api/issues/4[corresponding issue].
-* Shared Volumes Across Components. See https://github.com/devfile/api/issues/19[corresponding issue].
-* Out of Main Pod Components. See  https://github.com/devfile/api/issues/48[corresponding issue].
-* Replace Alias with Name. See  https://github.com/devfile/api/issues/9[corresponding issue].
-* Renaming dockerimage component type. See  https://github.com/devfile/api/issues/8[corresponding issue].
-* Specify sources path for containers. See  https://github.com/devfile/api/issues/17[corresponding issue].
-* Specify size of volume for component. See https://github.com/devfile/api/issues/14[corresponding issue].
-* Containers endpoints (routes/ingresses). See https://github.com/devfile/api/issues/27[corresponding issue].
+* link:https://github.com/devfile/api/issues/4[Polymorphic component type]
+* link:https://github.com/devfile/api/issues/19[Shared volumes across components]
+* link:https://github.com/devfile/api/issues/48[Out of main pod containers]
+* link:https://github.com/devfile/api/issues/9[Replace alias with name]
+* link:https://github.com/devfile/api/issues/8[Rename dockerimage component type]
+* link:https://github.com/devfile/api/issues/17[Specify source path for containers]
+* link:https://github.com/devfile/api/issues/14[Specify size of volume for components]
+* link:https://github.com/devfile/api/issues/27[Container endpoints: routes and ingresses]
diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
index 53bdc0f3..b8ed44de 100644
--- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
@@ -2,20 +2,20 @@
 = Migrating plug-ins
 
 [role="_abstract"]
-This section describes how to migrate plug-ins to devfile v2.x. Plug-ins are now specified using a devfile. A plug-in specified in a v1.0 `meta.yaml` does not work as it is in a devfile v2.x.
+This section describes how to migrate plug-ins to devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x.
 
-Additionally, v2.x devfiles include the following new features:
+Additionally, devfiles v2.x include the following new features:
 
 * Parents allow users to reuse an existing devfile and partially replace plug-in functionality.
-* Eclipse Che IDEs and their tooling can be specified as attributes in a v2.x devfile or in a distinct YAML file, for example: `.che/che-editor.yaml` or `.che/che-theia-plugin.yaml`.
+* Eclipse Che IDEs and their tooling can be specified as attributes in a devfile v2.x or in a distinct YAML file, for example: `.che/che-editor.yaml` or `.che/che-theia-plugin.yaml`.
 
 
 [role="_additional-resources"]
 .Additional resources
 
-To learn more about plug-ins in v2.x devfiles, go to the GitHub issues on the following topics:
+For a deeper understanding about plug-ins in devfiles v2.x, go to the following GitHub issues:
 
-* link:https://github.com/eclipse/che/issues/18669[Devfile plugins not suited to specify Che-Theia plugins].
-* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plugins support in devfile v2.x].
-* link:https://github.com/devfile/api/issues/364[Plugins' replacement].
-* link:https://github.com/devfile/api/issues/31[Better plugin mechanism].
+* link:https://github.com/eclipse/che/issues/18669[Devfile plug-ins not suited to specify Che-Theia plug-ins]
+* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plug-ins support in devfile v2.x]
+* link:https://github.com/devfile/api/issues/364[Plug-ins' replacement]
+* link:https://github.com/devfile/api/issues/31[Better plug-in mechanism]
diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
index e6616ef6..d6dad47a 100644
--- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
@@ -2,12 +2,12 @@
 = Migrating projects
 
 [role="_abstract"]
-There are NO major changes in the `projects` section of the devfile. A project specified in a v1.0 devfile will work as it is in a devfile v2.0.
+This section describes how to migrate projects to devfiles v2.x. A project specified in a devfile v1.x still works in a devfile v2.x.
 
 .Procedure
 
-*  The only major change is the addition of a new kind of project: `starterProjects`. Those are supposed to be used in interactive mode only (user pick one) and the git repo get not be cloned but only source code get copied (kind of what `git archive --remote=<repository URL> | tar -t` would do).
-+
+ Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
+
 .starterProjects and projects description
 ====
 [source,yaml]
@@ -24,4 +24,5 @@ starterProjects:
 
 [role="_additional-resources"]
 .Additional resources
-* See link:https://github.com/che-incubator/devworkspace-api/issues/42[corresponding issue].
+
+For a deeper understanding of migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
index cf8d7dc2..b11ab0df 100644
--- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
@@ -2,11 +2,11 @@
 = Migrating schema version
 
 [role="_abstract"]
-This section describes how to migrate schema version.
+This section describes how to migrate a schema version to devfiles v2.x. A schema version specified in a devfile v1.x still works in a devfile v2.x.
 
 .Procedure
 
-* Replace `apiVersion: 1.0.0` by `schemaVersion: 2.0.0`:
+To migrate a schema version from devfiles v1.x to devfiles v2.x, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`.
 
 [cols="1a,1a"]
 |====
@@ -34,4 +34,5 @@ metadata:
 
 [role="_additional-resources"]
 .Additional resources
-* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue]
+
+For a deeper understanding of migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].
diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
index 961f590d..262f0968 100644
--- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
+++ b/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
@@ -2,17 +2,22 @@
 = Refering to a parent devfile in a devfile
 
 [role="_abstract"]
-It is possible to refer to another devfile as a parent to a given devfile. If a parent is specified, the devfile will inherit all behaviour from the parent. Part of the content of the parent can be overridden in the child devfile. That allows refering a devfile (the parent) from a distinct devfile and makes it possible to reuse in multiple devfiles the same parent (the stack).
+This section describes how to designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent.  Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles.
 
 .Prerequisites
 
-* xref:adding-schema-version-to-a-devfile.adoc[]
-* xref:adding-a-name-to-a-devfile.adoc[]
+* Define the schemaVersion to v2.x. If you need to define your schemaVersion, go to xref:adding-schema-version-to-a-devfile.adoc[].
+* Define a name for the devfile. If you need to define a name for your devfile go to xref:adding-a-name-to-a-devfile.adoc[].
 
 
 .Procedure
 
-* A parent devfile can be referenced in 3 different ways: `registry`, `uri` or `kubernetes`.
+You can refer to a parent devfile in three different ways:
+
+* registry
+* uri
+* kubernetes
+
 +
 .Parent referred by registry
 ====
@@ -62,5 +67,7 @@ parent:
 [role="_additional-resources"]
 .Additional resources
 
+For a deeper understanding of referring to parent devfiles, go to the following topics:
+
 * xref:api-reference.adoc[]
 * xref:devfile-samples.adoc[]

From 709e6ee6668483f9eba23284bdd7d5cb49deb2e2 Mon Sep 17 00:00:00 2001
From: jc-berger <>
Date: Tue, 13 Apr 2021 15:37:23 -0400
Subject: [PATCH 2/5] formatting change

---
 docs/modules/user-guide/partials/proc_migrating-projects.adoc | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
index d6dad47a..2b0245a6 100644
--- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
@@ -6,12 +6,11 @@ This section describes how to migrate projects to devfiles v2.x. A project speci
 
 .Procedure
 
- Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
+Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
 
 .starterProjects and projects description
 ====
 [source,yaml]
-----
 v2.0
 ---
 starterProjects:
@@ -19,7 +18,6 @@ starterProjects:
     description: "Use this app to get a nodejs application for working with kafka"
   - name: "simple-project"
     description: "Use this app to get a simple "hello world" nodejs application"
-----
 ====
 
 [role="_additional-resources"]

From 3cc74a63930d2c06380efb156e4f796f31aaec27 Mon Sep 17 00:00:00 2001
From: jc-berger <>
Date: Wed, 14 Apr 2021 15:42:11 -0400
Subject: [PATCH 3/5] more doc changes

---
 .../partials/assembly_migrating-to-devfile-v2.adoc     |  4 ++--
 .../partials/proc_adding-event-bindings.adoc           |  4 ++--
 .../user-guide/partials/proc_migrating-commands.adoc   |  4 ++--
 .../user-guide/partials/proc_migrating-components.adoc |  6 +++---
 .../user-guide/partials/proc_migrating-plug-ins.adoc   | 10 +++++-----
 .../user-guide/partials/proc_migrating-projects.adoc   |  6 +++---
 .../partials/proc_migrating-schema-version.adoc        |  6 +++---
 ...oc_referring-to-a-parent-devfile-in-a-devfile.adoc} |  6 +++---
 8 files changed, 23 insertions(+), 23 deletions(-)
 rename docs/modules/user-guide/partials/{proc_refering-to-a-parent-devfile-in-a-devfile.adoc => proc_referring-to-a-parent-devfile-in-a-devfile.adoc} (90%)

diff --git a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
index f9199e70..ede8a86b 100644
--- a/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
+++ b/docs/modules/user-guide/partials/assembly_migrating-to-devfile-v2.adoc
@@ -11,7 +11,7 @@ endif::[]
 
 :context: assembly_migrating-to-devfile-v2
 
-The following documents explain how to migrate an existing devfile v1.x to a devfile v2.x:
+The following documents explain how to migrate an existing v1.x devfile to a v2.x devfile:
 
 * xref:migrating-schema-version.adoc[]
 * xref:migrating-projects.adoc[]
@@ -24,7 +24,7 @@ The following documents explain how to migrate an existing devfile v1.x to a dev
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understand of migrating devfiles, go to the following GitHub issues:
+For more information on migrating devfiles, go to the following GitHub issues:
 
 * link:https://github.com/devfile/api/issues/10[Devfile schema]
 * link:https://github.com/devfile/api/issues/31[Plug-in mechanism]
diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
index b37faef2..7a8bce80 100644
--- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
+++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
@@ -2,7 +2,7 @@
 = Adding event bindings
 
 [role="_abstract"]
-This section describes how to add an event to devfiles v2.x. An event specified in a devfile v1.x still works in a devfile v2.x.
+This section describes how to add an event to v2.x devfiles. An event specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
@@ -43,4 +43,4 @@ events:
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understand of adding event bindings, go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[lifecycle bindings to bind commands].
+For more information on adding event bindings, go to the following GitHub issue: link:https://github.com/devfile/api/issues/32[lifecycle bindings to bind commands].
diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
index a8d60b07..76dabede 100644
--- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
@@ -2,7 +2,7 @@
 = Migrating commands
 
 [role="_abstract"]
-This section describes how to migrate the `commands` section to devfiles v2.x. A command specified in a devfile v1.x does not work in a devfile v2.x.
+This section describes how to migrate the `commands` section to v2.x devfiles. A command specified in a v1.x devfile does not work in a v2.x devfile.
 
 .Procedure
 
@@ -18,7 +18,7 @@ This section describes how to migrate the `commands` section to devfiles v2.x. A
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding of migrating commands, go to the following GitHub issues:
+For more information on migrating commands, go to the following GitHub issues:
 
 * link:https://github.com/devfile/api/issues/27[Command groups: build, run, test, debug]
 * link:https://github.com/devfile/api/issues/56[Apply command]
diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc
index f2eba500..d2a0cc7b 100644
--- a/docs/modules/user-guide/partials/proc_migrating-components.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc
@@ -2,13 +2,13 @@
 = Migrating components
 
 [role="_abstract"]
-This section describes how to migrate components to devfiles v2.x. A component specified in a devfile v1.x no longer works in a devfile v2.x
+This section describes how to migrate components to v2.x devfiles. A component specified in a v1.x devfile no longer works in a v2.x devfile.
 
 .Procedure
 
 . Component is a polymorphic type
 +
-For a better syntax, the validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
+The validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
 +
 [source,yaml]
 ----
@@ -30,7 +30,7 @@ components:
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding of migrating components, go to the following GitHub issues:
+For more information on migrating components, go to the following GitHub issues:
 
 * link:https://github.com/devfile/api/issues/4[Polymorphic component type]
 * link:https://github.com/devfile/api/issues/19[Shared volumes across components]
diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
index b8ed44de..cd06a4f7 100644
--- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
@@ -2,20 +2,20 @@
 = Migrating plug-ins
 
 [role="_abstract"]
-This section describes how to migrate plug-ins to devfile v2.x. A plug-in specified in a meta.yaml in a devfile v1.x no longer works in a devfile v2.x.
+This section describes how to migrate plug-ins to a v2.x devfile. A plug-in specified in a `meta.yaml` in a v1.x devfile no longer works in a v2.x devfile.
 
-Additionally, devfiles v2.x include the following new features:
+Additionally, v2.x devfiles include the following new features:
 
 * Parents allow users to reuse an existing devfile and partially replace plug-in functionality.
-* Eclipse Che IDEs and their tooling can be specified as attributes in a devfile v2.x or in a distinct YAML file, for example: `.che/che-editor.yaml` or `.che/che-theia-plugin.yaml`.
+* Eclipse Che IDEs and their tooling can be specified as attributes in a v2.x devfile or in a distinct YAML file, for example: `.che/che-editor.yaml` or `.che/che-theia-plugin.yaml`.
 
 
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding about plug-ins in devfiles v2.x, go to the following GitHub issues:
+For more information on plug-ins in v2.x devfiles, go to the following GitHub issues:
 
 * link:https://github.com/eclipse/che/issues/18669[Devfile plug-ins not suited to specify Che-Theia plug-ins]
-* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plug-ins support in devfile v2.x]
+* link:https://github.com/eclipse/che/issues/18668[Che editors and Che-Theia plug-ins support in v2.x devfile]
 * link:https://github.com/devfile/api/issues/364[Plug-ins' replacement]
 * link:https://github.com/devfile/api/issues/31[Better plug-in mechanism]
diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
index 2b0245a6..5b18c941 100644
--- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
@@ -2,11 +2,11 @@
 = Migrating projects
 
 [role="_abstract"]
-This section describes how to migrate projects to devfiles v2.x. A project specified in a devfile v1.x still works in a devfile v2.x.
+This section describes how to migrate projects to v2.x devfiles. A project specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
-Devfiles v2.x has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
+V2.x devfiles has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
 
 .starterProjects and projects description
 ====
@@ -23,4 +23,4 @@ starterProjects:
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding of migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
+For more information on migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].
diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
index b11ab0df..34f4a078 100644
--- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
@@ -2,11 +2,11 @@
 = Migrating schema version
 
 [role="_abstract"]
-This section describes how to migrate a schema version to devfiles v2.x. A schema version specified in a devfile v1.x still works in a devfile v2.x.
+This section describes how to migrate a schema version to v2.x devfiles. A schema version specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
-To migrate a schema version from devfiles v1.x to devfiles v2.x, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`.
+To migrate a schema version from v1.x devfiles to v2.x devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`.
 
 [cols="1a,1a"]
 |====
@@ -35,4 +35,4 @@ metadata:
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding of migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].
+For more information on migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].
diff --git a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
similarity index 90%
rename from docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
rename to docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
index 262f0968..5138d18b 100644
--- a/docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc
+++ b/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
@@ -1,8 +1,8 @@
 [id="proc_refering-to-a-parent-devfile-in-a-devfile_{context}"]
-= Refering to a parent devfile in a devfile
+= Referring to a parent devfile in a devfile
 
 [role="_abstract"]
-This section describes how to designate a parent devfile to a given devifle. If you designate a parent devfile, the given devfile inherits all its behavior from its parent.  Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles.
+This section describes how to designate a parent devfile to a given devfile. If you designate a parent devfile, the given devfile inherits all its behavior from its parent.  Still, you can use the child devfile to override certain content from the parent devfile. If you override the correct content, you can reuse the same parent devfile in multiple other devfiles. If you do reuse a parent devfile, the parent turns into a stack that is used in multiple other devfiles.
 
 .Prerequisites
 
@@ -67,7 +67,7 @@ parent:
 [role="_additional-resources"]
 .Additional resources
 
-For a deeper understanding of referring to parent devfiles, go to the following topics:
+For more information on referring to parent devfiles, go to the following topics:
 
 * xref:api-reference.adoc[]
 * xref:devfile-samples.adoc[]

From 1854635e42f974adb5f375958c56e48c9787f227 Mon Sep 17 00:00:00 2001
From: jc-berger <>
Date: Thu, 15 Apr 2021 14:13:51 -0400
Subject: [PATCH 4/5] changed toc b/c renamed doc; more doc changes

---
 docs/modules/user-guide/nav.adoc                       |  4 ++--
 .../user-guide/partials/proc_migrating-components.adoc |  2 +-
 .../user-guide/partials/proc_migrating-plug-ins.adoc   |  2 +-
 .../user-guide/partials/proc_migrating-projects.adoc   |  2 +-
 .../partials/proc_migrating-schema-version.adoc        |  9 ++++-----
 ...roc_referring-to-a-parent-devfile-in-a-devfile.adoc | 10 +++++-----
 6 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/docs/modules/user-guide/nav.adoc b/docs/modules/user-guide/nav.adoc
index ef833c4e..3452be05 100644
--- a/docs/modules/user-guide/nav.adoc
+++ b/docs/modules/user-guide/nav.adoc
@@ -16,7 +16,7 @@
 
 ** xref:adding-attributes-to-a-devfile.adoc[]
 ** xref:adding-event-bindings.adoc[]
-** xref:refering-to-a-parent-devfile-in-a-devfile.adoc[]
+** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
 
 * xref:migrating-to-devfile-v2.adoc[]
 ** xref:migrating-schema-version.adoc[]
@@ -25,7 +25,7 @@
 ** xref:migrating-plug-ins.adoc[]
 ** xref:migrating-commands.adoc[]
 ** xref:adding-event-bindings.adoc[]
-** xref:refering-to-a-parent-devfile-in-a-devfile.adoc[]
+** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]
 
 * xref:api-reference.adoc[]
 * xref:devfile-samples.adoc[]
diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc
index d2a0cc7b..33215b3a 100644
--- a/docs/modules/user-guide/partials/proc_migrating-components.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc
@@ -8,7 +8,7 @@ This section describes how to migrate components to v2.x devfiles. A component s
 
 . Component is a polymorphic type
 +
-The validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
+The validation component is now defined as a polymorphic type and can be implemented as, `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
 +
 [source,yaml]
 ----
diff --git a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
index cd06a4f7..d1180c68 100644
--- a/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-plug-ins.adoc
@@ -2,7 +2,7 @@
 = Migrating plug-ins
 
 [role="_abstract"]
-This section describes how to migrate plug-ins to a v2.x devfile. A plug-in specified in a `meta.yaml` in a v1.x devfile no longer works in a v2.x devfile.
+This section describes how to migrate plug-ins to a v2.x devfile. A plug-in specified in a `meta.yaml` for a v1.x devfile no longer works in a v2.x devfile.
 
 Additionally, v2.x devfiles include the following new features:
 
diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
index 5b18c941..0d96f54e 100644
--- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
@@ -6,7 +6,7 @@ This section describes how to migrate projects to v2.x devfiles. A project speci
 
 .Procedure
 
-V2.x devfiles has a new kind of project: `starterProjects`. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your git repository.
+A new `starterProjects` project type can be defined in v2.x devfiles. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your Git repository.
 
 .starterProjects and projects description
 ====
diff --git a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
index 34f4a078..d64851c6 100644
--- a/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-schema-version.adoc
@@ -2,12 +2,12 @@
 = Migrating schema version
 
 [role="_abstract"]
-This section describes how to migrate a schema version to v2.x devfiles. A schema version specified in a v1.x devfile still works in a v2.x devfile.
+This section describes how to migrate the existing schema version to a v2.x devfile. The schema version specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
-To migrate a schema version from v1.x devfiles to v2.x devfiles, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`.
-
+. To migrate a schema version from a v1.x devfile to a v2.x devfile, replace `apiVersion: 1.0.0` with `schemaVersion: 2.0.0`:
++
 [cols="1a,1a"]
 |====
 |
@@ -29,8 +29,7 @@ metadata:
   name: devfile-sample
 ----
 |====
-
-
++
 
 [role="_additional-resources"]
 .Additional resources
diff --git a/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc b/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
index 5138d18b..011d5701 100644
--- a/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
+++ b/docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc
@@ -6,17 +6,17 @@ This section describes how to designate a parent devfile to a given devfile. If
 
 .Prerequisites
 
-* Define the schemaVersion to v2.x. If you need to define your schemaVersion, go to xref:adding-schema-version-to-a-devfile.adoc[].
-* Define a name for the devfile. If you need to define a name for your devfile go to xref:adding-a-name-to-a-devfile.adoc[].
+* Define the `schemaVersion` to v2.x. If you need to define your `schemaVersion`, go to xref:adding-schema-version-to-a-devfile.adoc[].
+* Define a name for the devfile. If you need to define a name for your devfile, go to xref:adding-a-name-to-a-devfile.adoc[].
 
 
 .Procedure
 
 You can refer to a parent devfile in three different ways:
 
-* registry
-* uri
-* kubernetes
+* `registry`
+* `uri`
+* `kubernetes`
 
 +
 .Parent referred by registry

From 687113bbbef354ae970d0be6b3655644f358dcfe Mon Sep 17 00:00:00 2001
From: jc-berger <>
Date: Fri, 16 Apr 2021 11:52:28 -0400
Subject: [PATCH 5/5] final doc changes

---
 .../modules/user-guide/partials/proc_adding-event-bindings.adoc | 2 +-
 docs/modules/user-guide/partials/proc_migrating-commands.adoc   | 2 +-
 docs/modules/user-guide/partials/proc_migrating-components.adoc | 2 +-
 docs/modules/user-guide/partials/proc_migrating-projects.adoc   | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
index 7a8bce80..4e32e70d 100644
--- a/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
+++ b/docs/modules/user-guide/partials/proc_adding-event-bindings.adoc
@@ -2,7 +2,7 @@
 = Adding event bindings
 
 [role="_abstract"]
-This section describes how to add an event to v2.x devfiles. An event specified in a v1.x devfile still works in a v2.x devfile.
+This section describes how to add an event to a v2.x devfile. An event specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
diff --git a/docs/modules/user-guide/partials/proc_migrating-commands.adoc b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
index 76dabede..f0426395 100644
--- a/docs/modules/user-guide/partials/proc_migrating-commands.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-commands.adoc
@@ -2,7 +2,7 @@
 = Migrating commands
 
 [role="_abstract"]
-This section describes how to migrate the `commands` section to v2.x devfiles. A command specified in a v1.x devfile does not work in a v2.x devfile.
+This section describes how to migrate the `commands` section to a v2.x devfile. A command specified in a v1.x devfile does not work in a v2.x devfile.
 
 .Procedure
 
diff --git a/docs/modules/user-guide/partials/proc_migrating-components.adoc b/docs/modules/user-guide/partials/proc_migrating-components.adoc
index 33215b3a..a2e938b8 100644
--- a/docs/modules/user-guide/partials/proc_migrating-components.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-components.adoc
@@ -8,7 +8,7 @@ This section describes how to migrate components to v2.x devfiles. A component s
 
 . Component is a polymorphic type
 +
-The validation component is now defined as a polymorphic type and can be implemented as, `container`, `kubernetes`, `openshift`, `plugin` or `volume`.
+The validation component is now defined as a polymorphic type and can be implemented as `container`, `kubernetes`, `openshift`, `plugin`, or `volume`.
 +
 [source,yaml]
 ----
diff --git a/docs/modules/user-guide/partials/proc_migrating-projects.adoc b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
index 0d96f54e..7a579a39 100644
--- a/docs/modules/user-guide/partials/proc_migrating-projects.adoc
+++ b/docs/modules/user-guide/partials/proc_migrating-projects.adoc
@@ -6,7 +6,7 @@ This section describes how to migrate projects to v2.x devfiles. A project speci
 
 .Procedure
 
-A new `starterProjects` project type can be defined in v2.x devfiles. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your Git repository.
+A new `starterProject` project type can be defined in v2.x devfiles. Pick only one `starterProject` and use it in interactive mode. With a `starterProject`, you only need to copy your source code, so you no longer need to clone your Git repository.
 
 .starterProjects and projects description
 ====