From b732e1b8dd09e2be3240f7663f1c5d7d0826b9b7 Mon Sep 17 00:00:00 2001
From: Tiffany K <tiffanykyi@gmail.com>
Date: Wed, 4 Apr 2018 17:27:30 -0700
Subject: [PATCH] fix(911): Update source paths with repo file structure
 example (#163)

---
 docs/user-guide/configuration/sourcePaths.md | 45 +++++++++++++++-----
 1 file changed, 34 insertions(+), 11 deletions(-)

diff --git a/docs/user-guide/configuration/sourcePaths.md b/docs/user-guide/configuration/sourcePaths.md
index abb09d07..78b1f334 100644
--- a/docs/user-guide/configuration/sourcePaths.md
+++ b/docs/user-guide/configuration/sourcePaths.md
@@ -11,21 +11,44 @@ toc:
 # Source Paths
 Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git).
 
-
-_Note: This feature is only available for [Github SCM](https://github.com/screwdriver-cd/scm-github)._
-
 ## Types of source paths
-You can either specify subdirectories and/or specific files as source paths. To denote a subdirectory, leave a trailing slash (`/`) at the end.
+You can either specify subdirectories and/or specific files as source paths. To denote a subdirectory, leave a trailing slash (`/`) at the end. The path is relative to the root of the repository.
 
 #### Example
-In the following example, the job `main` will start after any SCM pull-request, _or_ commit event on files under `src/app/` or the `screwdriver.yaml` file.
+
+Given a repository with the file structure depicted below:
+
+```
+┌── README.md
+├── screwdriver.yaml
+├── test/
+│   └── ...
+├── src/
+│   ├── app/
+│   │   ├── main.js
+│   │   ├── ...
+│   │   └── package.json
+│   └── other/
+│       └── ...
+│
+...
+```
+
+And the `screwdriver.yaml`:
 
 ```yaml
 jobs:
-      main:
-            image: node:6
-            requires: [~pr, ~commit]
-            sourcePaths: ["src/app/", "screwdriver.yaml"]
-            steps:
-                - echo: echo hi
+    main:
+        image: node:6
+        requires: [~pr, ~commit]
+        sourcePaths: ["src/app/", "screwdriver.yaml"]
+        steps:
+            - echo: echo hi
 ```
+
+In this example, the job `main` will be triggered if there are any changes to files under `src/app/` or the `screwdriver.yaml` file (like on `src/app/main.js`, `src/app/package.json`, etc.). The `main` job will **not**, however, be triggered on changes to `README.md`, `test/`, or `src/other/`.
+
+### Caveats
+- This feature is only available for the [Github SCM](https://github.com/screwdriver-cd/scm-github) right now.
+- `sourcePaths` will be ignored if you manually start a pipeline or restart a job.
+- The `screwdriver.yaml` must still be located at root.