Added diagram

Troubleshooting-issues-with-samples.md

@@ -5,14 +5,41 @@ This article should help you resolve the majority of issues, starting with the m
 Once you have performed the steps in this article, you can proceed with creating an issue -- but make sure to read [how to create good issues](How-to-create-good-issues) first, because the people who support these samples are all volunteers, and we certainly want to be respectful of their time, *don't we*?
 
 ```mermaid
-sequenceDiagram
-  A->> B: Query
-  B->> C: Forward query
-  Note right of C: Thinking...
-  C->> B: Response
-  B->> A: Forward response
+graph TD
+    A[Get web part sample code] 
+    A -->|Open repo/unzip folder| B(npm install)
+    B --> C{Any errors?}
+    C -->|Yes| D{In same folder as package.json?}
+    C -->|No| E(gulp build)
+    E --> F{Does in build?}
+    D -->|No| G(Change directory) --> |Retry|B
+    D -->|Yes| H{Path too long?}
+    H -->|Yes| I(Change directory) --> |Retry|B
+    H -->|No| J(Run spfx doctor)
+    click J "https://github.com/pnp/sp-dev-fx-webparts/wiki/Troubleshooting-issues-with-samples#run-spfx-doctor"
+    J --> K{Compatibilty issues?} -->|Yes| L(Fix Compatibilty issues) -->|Retry|B
+    J -->|No| M(Open an issue)
+
 ```
 
+## `npm install` stops with errors
+
+Please note that warnings will rarely prevent the solution from working; We only worry about errors.
+
+### `npm WARN saveError ENOENT: no such file or directory`
+
+Make sure that you are running `npm install` in the root folder where the web part code is located. There should be an existing `package.json` file. **Do not** create a `package.json`, because the solution must already have one -- otherwise it would not have been accepted as a sample.
+
+If you're already currently in the root of the sample solution, take a look to see if the sample contains sub-components; are there any folders named `webparts` (or something similar)? If so, try looking for the `README.md` for instructions on how to build the sample.
+
+### `Build FAILED`
+
+You should see at least one line showing `npm ERR!` in the many many lines of diagnostics after running `npm install`.
+
+Look for messages such as `Not compatible with your version of node/npm`.
+
+Try [#run-spfx-doctor](running `spfx doctor`) to make sure your environment is compatible with the solution.
+
 ## Sample won't build
 
 ![Symptoms: Won't build](https://img.shields.io/badge/Symptoms-Won%27t%20build-critical?style=for-the-badge&logo=nodedotjs)
@@ -76,6 +103,7 @@ To do so, follow these steps:
    ```bash
    npm i -g @pnp/cli-microsoft365
    ```
+
 1. With the CLI installed, change your command prompt's current directory to the root of the sample's solution. Although it is often the same folder containing the `README.md`, some more complex samples may have multiple solutions in multiple sub-folders. The root will contain a `package.json`.
 
     You can confirm that you are within the solution's root folder by using your command prompt to enter the following command:
@@ -83,6 +111,7 @@ To do so, follow these steps:
     ```bash
     ls package.json
     ```
+
     If it returns a single `package.json`, you are in the right folder. If you get `ls: cannot access 'package.json': No such file or directory`, make sure to change the current folder (using `cd`, followed by the full path of where your sample is stored).
 
 1. Using your command prompt, enter the following command:
@@ -119,10 +148,13 @@ To do so, follow these steps:
     ```bash
     m365 spfx doctor -o json
     ```
+
     Copy the output and [open a new bug report](https://github.com/pnp/sp-dev-fx-webparts/issues/new?assignees=&labels=type%3Abug-suspected&template=bug-report.yml)
+
 ### Alternatives
 
 #### Recommended
+
 If you are unable to update your environment to run the solution, consider the following alternatives:
 
 - [Open the sample in a remote container](https://github.com/pnp/sp-dev-fx-webparts/wiki/Opening-a-sample-using-a-development-container)