Made docs adhere to style guide (#51)

* made docs adhere to style guide

* formatting change

* more doc changes

* changed toc b/c renamed doc; more doc changes

* final doc changes

Co-authored-by: jc-berger <>

Author: jc-berger

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[]

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 v1.x devfile to a v2.x devfile:
 
 * 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 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]
 
 
 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:]
-

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 a v2.x devfile. An event specified in a v1.x devfile still works in a v2.x devfile.
 
 .Procedure
 
@@ -46,4 +42,5 @@ events:
 
 [role="_additional-resources"]
 .Additional resources
-* See https://github.com/che-incubator/devworkspace-api/issues/32[corresponding issue].
+
+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].

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 a v2.x devfile. A command specified in a v1.x devfile does not work in a v2.x devfile.
 
 .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 more information on 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]

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 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 validation component now is 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]
 ----
@@ -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 more information on 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]

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 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 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:
 
@@ -13,9 +13,9 @@ Additionally, v2.x devfiles include the following new features:
 [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 more information on plug-ins in v2.x devfiles, 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 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]

docs/modules/user-guide/partials/proc_migrating-projects.adoc

@@ -2,26 +2,25 @@
 = 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 v2.x devfiles. A project specified in a v1.x devfile still works in a v2.x devfile.
 
 .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).
-+
+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
 ====
 [source,yaml]
-----
 v2.0
 ---
 starterProjects:
   - name: "kafka-project"
     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"]
 .Additional resources
-* See link:https://github.com/che-incubator/devworkspace-api/issues/42[corresponding issue].
+
+For more information on migrating projects, go to the following GitHub issue: link:https://github.com/devfile/api/issues/42[starterProjects].

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 schema version.
+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
 
-* Replace `apiVersion: 1.0.0` by `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,9 +29,9 @@ metadata:
   name: devfile-sample
 ----
 |====
-
-
++
 
 [role="_additional-resources"]
 .Additional resources
-* See link:https://github.com/che-incubator/devworkspace-api/issues/7[corresponding issue]
+
+For more information on migrating schema versions, go to the following GitHub issue: link:https://github.com/devfile/api/issues/7[schemaVersion attribute].

docs/modules/user-guide/partials/proc_refering-to-a-parent-devfile-in-a-devfile.adoc renamed to docs/modules/user-guide/partials/proc_referring-to-a-parent-devfile-in-a-devfile.adoc

@@ -1,18 +1,23 @@
 [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"]
-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 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
 
-* 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 more information on referring to parent devfiles, go to the following topics:
+
 * xref:api-reference.adoc[]
 * xref:devfile-samples.adoc[]