Improve doc

vmware-tanzu · Jan 23, 2023 · bab97e2 · bab97e2
1 parent 3e9d893
commit bab97e2
Showing 1 changed file with 12 additions and 6 deletions.
diff --git a/docs/getting_started/UpgradingDatamodel.md b/docs/getting_started/UpgradingDatamodel.md
@@ -2,6 +2,10 @@
 
 This workflow will walk you through the steps to upgrade your applocal datamodel.
 
+## Purpose
+
+The purpose of Datamodel Upgrade is to make it possible to reinstall Datamodel without having to first uninstall and then reinstall it.
+
 * [Pre-requisites](UpgradingDatamodel.md#pre-requisites)
 * [Upgrading](UpgradingDatamodel.md#Upgrading)
 
@@ -12,8 +16,8 @@ This workflow will walk you through the steps to upgrade your applocal datamodel
 
 ## Upgrading
 
-1. Make changes to root.go file in your datamodel, remove one field, change name of another and add one.
- These changes are incompatible (although added filed wouldn't be, if it would have `json:"omitempty"` tag )
+1. Make changes to the root.go file in your datamodel by remove one field, renaming another and adding one.
+ These datamodel changes are incompatible (although the newly added field wouldn't be incompatible if it had the `json:"omitempty"` tag )
  ```shell
  cat <<< '--- root.go.orig 2023-01-05 04:22:07.475996737 -0800
  +++ root.go 2023-01-17 05:41:07.993795597 -0800
@@ -61,9 +65,9 @@ This workflow will walk you through the steps to upgrade your applocal datamodel
 ### Common parameters(Build + Install)
 
 
-| Name  | Description |  Type  | Short | Value  |
-|--------------------|------------------------------|:------:|:-----:|:---------------|
-| `force`  | Force upgrade of a datamodel |  bool  | f | `false`  |
+| Name | Description | Type | Shorthand | Value |
+|---------|------------------------------|:----:|:---------:|:--------|
+| `force` | Force upgrade of a datamodel | bool |  f  | `false` |
 
 
 ### Build parameters
@@ -84,7 +88,9 @@ $ nexus datamodel build --name orgchart --force=false --prev-spec-dir=<build/crd
 
 The above command builds the new datamodel against the master branch of the build/crds directory.
 
-## Compatibility
+## Ensure Backwards Compatibility
+
+Please read the following scenarios to learn more about backwards compatibility.
 
 | Use Cases | force=false | force=true |
 |-------------------------------------------------------|:-----------:|:----------:|