Merge pull request #1195 from newrelic/tutorial-updates

chore: Update Tutorial how-to

COMPONENT_GUIDE.md

@@ -168,95 +168,191 @@ A step description
 
 > Note: keep in mind that a new line is necessary after an `img` tag to ensure proper rendering of subsequent text/markdown.
 
-# Tutorial 
+# Tutorial
 
 ## Usage
 
-The `<Tutorial/>` component can be used to help a user step through changes in code by highlighting the difference between each step. It utilizes children `<Steps>` and `<Step>` components to find codeblocks with new code based off of the starting code. You can set the starting code as the first child of the `<Tutorial>` with the `<Project>` component. In order to use the tutorial component, you must set a `fileName` for your codeblocks so that the parser can find the corresponding codeblocks with changes in them. 
+You can use the `Tutorial` component walk a user through changes in code by automatically highlighting the difference between each step.
+
+### Define your starting codebase
+
+First, use a `Project` component to define your starting codebase:
 
 ````md
-  <Tutorial>
+<Tutorial>
+
+<Project>
+
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+```
 
-  <Project>
+```jsx fileName=second-file.js
+const myCode = "here is my second file"
+```
 
-  ```jsx fileName="myfile.js"
-  const myCode = "here is my starting code" 
-  ```
+</Project>
 
-  </Project>
+</Tutorial>
+````
 
-  ## Here is my tutorial! 
+In order to use the tutorial component, you must set a `fileName` for your codeblocks so that the parser can find the corresponding codeblocks with changes in them.
 
-  <Steps>
+Note that you can set up multiple code files in your `Project` component. The parser will track changes in each of the codeblocks throughout the `Tutorial`. Each codeblock is presented in its own tab, which mimics how a user might actually edit these files in their IDE.
 
-  <Step>
+### Update code in tutorial steps
 
-  ```jsx fileName="myfile.js"
-  const myCode = "here is my code" 
-  const myNewCode = "here is my new code"
-  ```
+Use `Steps` to show changes to your starting files:
 
-  </Step>
+````md
+<Tutorial>
 
-  <Step>
+<Project>
 
-  ```jsx fileName="myfile.js"
-  const myCode = "here is my code" 
-  const myNewCode = "here is my new code"
-  const evenMoreNewCode = "he is even more new code"
-  ```
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+```
 
-  </Step>
+```jsx fileName=second-file.js
+const myCode = "here is my second file"
+```
+
+</Project>
+
+## Here is my tutorial!
+
+<Steps>
+
+<Step>
+
+Update your first file:
+
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+const myNewCode = "here is my new code"
+```
+
+</Step>
+
+<Step>
+
+Update your second file:
+
+```jsx fileName=second-file.js
+const myCode = "here is my second file"
+const myNewCode = "here is my new code"
+```
+
+</Step>
+
+<Step>
+
+Update your first file again:
+
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+const myNewCode = "here is my new code"
+const evenMoreNewCode = "here is even more new code"
+```
+
+</Step>
+
+</Steps>
 
-  </Tutorial>
+</Tutorial>
 ````
 
-In this example, for the first step the second line (`myNewCode`) will be highlighted, and for the second step, the third line (`evenMoreNewCode`) will be highlighted.
+In the first step's rendered codeblock, the second line (`myNewCode`) in _first-file.js_ will be highlighted. In the second step, the second line (`myNewCode`) in second-file.js_ will be highlighted. In the third step, the third line (`evenMoreNewCode`) iin _first-file.js_ will be highlighted.
 
-You can also pass in multiple codeblocks to the `<Project>` component and the parser will track all changes in each of the codeblocks. The multiple codeblocks will show up as tabs of the same editor, mimicking how a user might actually be editing these files in their IDE. For example: 
+Even though a single file is highlighted in each step, all files are rendered in tabs for each step on the page. Your reader can then toggle between the files to see what the current state of the whole codebase is.
+
+## Things to keep in mind
+
+Here are some things to keep in mind when using the `Tutorial` component in your developer guides.
+
+### Only change code in one file per step
+
+While every file is shown in a tabulated codeblock in every step, you can only change code in one file per step. This is because when you include a file change in a `Tutorial` step, the file that was changed is presented first in the tabulated codeblock.
+
+`Tutorial` doesn't know how to render a tabulated codeblock when multiple files are changed in the same step:
 
 ````md
-  <Tutorial>
+<Tutorial>
+
+<Project>
+
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+```
+
+```jsx fileName=second-file.js
+const myCode = "here is my second file"
+```
+
+</Project>
+
+## Here is my tutorial!
+
+<Steps>
+
+<Step>
+
+Update your first file and second file in the same step:
+
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+const myNewCode = "here is my new code"
+```
+
+```jsx fileName=second-file.js
+const myCode = "here is my second file"
+const myNewCode = "here is my new code"
+```
+
+</Step>
+
+</Steps>
+
+</Tutorial>
+````
 
-  <Project>
+This won't render properly in your guide.
 
-  ```jsx fileName="myfile.js"
-  const myCode = "here is my starting code" 
-  ```
+### `Tutorial` doesn't show subtractive changes
 
-  ```css fileName="mystyles.css"
-  .myStyle {
-    color: blue;
-  } 
-  ```
+Some code diff tools show additive changes (you created a new line) and subtractive changes (you deleted a line). `Tutorial` doesn't call to attention any code deletions.
 
-  </Project>
+````md
+<Tutorial>
 
-  ## Here is my tutorial! 
+<Project>
 
-  <Steps>
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+const moreCode = "here is more code"
+const evenMoreCode = "here is even more code"
+```
 
-  <Step>
+</Project>
 
-  ```jsx fileName="myfile.js"
-  const myCode = "here is my code" 
-  const myNewCode = "here is my new code"
-  ```
+## Here is my tutorial!
 
-  </Step>
+<Steps>
 
-  <Step>
+<Step>
 
-  ```css fileName="mystyles.css"
-  .myStyle {
-    color: blue;
-    font-size: 1000px;
-  } 
-  ```
+Delete `moreCode`:
 
-  </Step>
+```jsx fileName=first-file.js
+const myCode = "here is my first file"
+const evenMoreCode = "here is even more code"
+```
+
+</Step>
+
+</Steps>
 
-  </Tutorial>
+</Tutorial>
 ````
 
-In this example, in the first step, line 2 will be highlighted (`myNewCode`) and in the second step, line 3 will be highlighted (`font-size: 1000px`). Both steps will have both files, where as the default file shown will be `myfile.js` for the first step and `mystyles.css` for the second step. Users can toggle between the two files to see what the current state of the code is.
+In this case, `Tutorial` will show _first-file.js_, but it won't indicate that the second constant (`moreCode`) was removed.