Making the documentation more applicable to its main audience; {N}ewbs!

docs/plugins/building-plugins.md

@@ -24,10 +24,14 @@ At their basic level NativeScript plugins are simple JavaScript modules that use
 
 ```
 nativescript-hello-world/
-├── index.js
-└── package.json
+└── src
+    ├── index.js
+    └── package.json
 ```
 
+>IMPORTANT: Putting your source in sub-folder is required for local live sync debugging.  
+>Existing plugins should be updated to move their source code in to a subfolder.
+
 And here is the simplest possible implementation of that plugin.
 
 ``` JavaScript
@@ -60,10 +64,10 @@ There are a few things to note in this implementation.
 
 > **TIP**: Other than the `"nativescript"` key, everything about your plugin’s `package.json` file will be identical to any other npm package. Therefore, [npm own’s docs on the `package.json` file](https://docs.npmjs.com/files/package.json) is a great reference when tinkering with your NativeScript plugin’s metadata during development.
 
- To use the above plugin all you need to do is install the plugin in one of your apps.
+To use the above plugin all you need to do is install the plugin in one of your apps.
 
 ```
-tns plugin add /path/to/nativescript-hello-world
+tns plugin add /path/to/nativescript-hello-world/src
 ```
 
 > **TIP**: The `tns plugin add` command lets you install plugins from non-npm locations, such as GitHub repos and local folders. For details, run `tns plugin add --help` on your command line.

docs/plugins/debugging-plugins.md

@@ -8,49 +8,82 @@ publish: true
 
 # Debugging Plugins
 
-Debugging a plugin is not much different than debugging a NativeScript app but needs some preparation to ease the plugin development. Before you continue, make sure you have covered the topics about [Debugging]({% slug debugging %}) and [NativeScript extension for Visual Studo Code]({% slug nativescript-extension-for-visual-studio-code %}). 
+Live sync debugging updates your demo/test app automatically in the simulator/device whenever you make a change in the plugin source code. Debugging a plugin is not much different than debugging a NativeScript app but needs some preparation to ease the plugin development. Before you continue, make sure you have covered the topics about [Debugging]({% slug debugging %}) and [NativeScript extension for Visual Studo Code]({% slug nativescript-extension-for-visual-studio-code %}). 
 
 What this article covers:
 
-* [The Problem](#Theproblem)
-* [Linking Your Plugin in the Demo App](#Linkingyourplugininthedemoapp)
+* [Setup](#Setup)
+* [Enabling](#Enabling)
 * [Debugging](#Debugging)
+* [Disabling](#Disabling)
 * [Limitations](#Limitations)
 
-##  <a name='Theproblem'></a>The Problem
+## <a name='Setup'></a>Setup
 
-Having your plugin developed separately from your plugin demo app makes debugging and development a tedious task. Relying only on the `tns plugin add\remove` commands slows down the development since on every change the commands need to be run to preview your changes in the demo app.
+Live sync debugging requires your plugin's source code to not be in the root of its home folder.
 
-What would be the ultimate goal is to be able to debug your plugin as part of the demo application with the option to make ad hoc changes in the plugin source code and preview them immediately. In addition it would be also convenient to get advantage of the live sync and have your demo automatically updated in the simulator/device when you make a change in the plugin source code.
+Bad:
+```
+nativescript-my-plugin/
+├── index.js
+└── package.json
+```
+Good:
+```
+nativescript-my-plugin/
+├── demo
+└── src
+    ├── index.js
+    └── package.json
+```
 
-##  <a name='Linkingyourplugininthedemoapp'></a>Linking Your Plugin in the Demo App
+>For the technically curious, this is because the build process will copy your plugin's source code folder, including **all** of its files, to their respective android/ios platform folder(s) prior to transpiling. If that process copied your project's root folder then it would also be copying your hidden/system (ex: .git) folders their respective android/ios platform folder(s); that would be bad.
 
-Achieving the goal descibed above is possible by using `npm link` during plugin development. 
+If you created your plugin using the [NativeScript plugin seed](https://github.com/NativeScript/nativescript-plugin-seed) then you are already set up!
 
-Boostrapping your plugin by using the [NativeScript plugin seed](https://github.com/NativeScript/nativescript-plugin-seed) links your plugin in the demo app out of the box on the `postclone` step. 
+If you did not create your plugin using the [NativeScript plugin seed](https://github.com/NativeScript/nativescript-plugin-seed) then just make sure that, per the example above, your plugin's source code is not in your project's root folder.
 
->NOTE: The instructions below are valid for npm 4 only. From npm 5 running `npm install` adds sym links by default. [Read more about `npm install`](https://docs.npmjs.com/cli/install).
->
->If you have your custom plugin structure you can still enable `npm link` by following the steps below:
->- Make sure your plugin code parent folder is different than the parent folder of your demo. See  [NativeScript plugin seed]>(https://github.com/NativeScript/nativescript-plugin-seed) for example where the plugin code is located in the `src` folder and demo is located in the `demo` folder, both on the root level. In terminal run:
->* `cd <your-plugin-folder>`
->* `npm link` to link your plugin in the global `node_modules` folder. [Read more about `npm link`](https://docs.npmjs.com/cli/link)
->* `cd <your-demo-folder>` to navigate to your demo folder
->* `npm link <your-plugin-name>`
->
->Now the files under `<your-demo-folder>/node_modules/<your-plugin-name>` are physically the same files that are located under `src`. >This means that making changes in `<your-demo-folder>/node_modules/<your-plugin-name>` will actually change the plugin source files. 
->
->If at some point you're ready with the development and want to test how your plugin behaves on running `tns plugin add/remove` you can >easily unlink your plugin by running Terminal:
->* `cd <your-demo-folder>`-
->* `npm unlink <your-plugin-name>`
->* `cd <your-plugin-folder>`
->* `npm unlink`
+>If you are debugging an existing or third party plugin, many of them may not be updated and properly structured to support live sync debugging. If a plugin's source code is in the project's root folder and not in a subfolder then you will need to move its source code out of the root folder and in to a subfolder. We encourage you to fork the plugin's original repo and create a Pull Request of your changes back to the plugin's original repo.
 
-##  <a name='Debugging'></a>Debugging
+## <a name='Enabling'></a>Enabling
+
+To enable local live sync debugging of you plugin in a demo/test app:
+
+1. `cd /your-demo-or-test-folder`
+2. `tns plugin add ../relative-path-to/your-plugin/src`
+
+If you are using npm 5 then this will automatically create a `npm link` in your demo/test app's node_modules folder to point to your plugin's source code.
+
+If you are using npm 4 then this will have copied your plugin's files instead of linking directly to them. You will need to manually perform the following additional step(s):
+
+3. `npm link ../relative-path-to/your-plugin/src`
+
+Now the files under `/your-demo-or-test-folder/node_modules/your-plugin` are physically the same files that are located under `your-plugin/src`. This means that you can edit either `/your-demo-or-test-folder/node_modules/your-plugin` or ``your-plugin/src` and the changes will automatically update in the demo/test app. 
+
+## <a name='Debugging'></a>Debugging
 
 Having the `npm link` set up, you can start debugging your demo project along with your plugin code in `node_modules` folder. Read more about [Debugging using `tns debug`]({% slug debugging %}) and [debugging using NativeScript extension for Visual Studo Code]({% slug nativescript-extension-for-visual-studio-code %}).
 
-##  <a name='Limitations'></a>Limitations
+## <a name='Disabling'></a>Disabling
+
+You may want disable debugging your local code if you are done developing or have published your plugin and want to test what the rest of the world will experience when they install your public.
+
+To disable local live sync debugging of you plugin and install your public plugin in a demo/test app:
+
+1. `cd /your-demo-or-test-folder`
+2. `tns plugin remove your-plugin`
+
+If you are using npm 5 then this will automatically call `npm unlink`.
+
+If you are using npm 4 then you will need to perform the following additional step(s):
+
+3. `npm unlink your-plugin`
+
+Now, add back the dependency to your public plugin:
+
+4. `tns plugin add you-plugin`
+
+## <a name='Limitations'></a>Limitations
 
 Using `npm link` eases the development of your plugin when you do any kind of code changes to your page templates, typescript/javascript, css files. What it won't do for you is to apply plugin changes to your demo related to:
 

docs/plugins/plugin-reference.md

@@ -53,36 +53,39 @@ NativeScript plugins which consist of one CommonJS module might have the followi
 
 ```
 my-plugin/
-├── index.js
-├── package.json
-└── platforms/
-    ├── android/
-    │   ├── res/
-    │   └── AndroidManifest.xml
-    └── ios/
-        └── Info.plist
+└── src
+    ├── index.js
+    ├── package.json
+    └── platforms/
+        ├── android/
+        │   ├── res/
+        │   └── AndroidManifest.xml
+        └── ios/
+            └── Info.plist
 ```
 
 NativeScript plugins which consist of multiple CommonJS modules might have the following directory structure.
 
 ```
 my-plugin/
-├── index.js
-├── package.json
-├── MyModule1/
-│   ├── index1.js
-│   └── package.json
-├── MyModule2/
-│   ├── index2.js
-│   └── package.json
-└── platforms/
-    ├── android/
-    │   ├── AndroidManifest.xml
-    │   └── res/
-    └── ios/
-        └── Info.plist
+└── src
+    ├── index.js
+    ├── package.json
+    ├── MyModule1/
+    │   ├── index1.js
+    │   └── package.json
+    ├── MyModule2/
+    │   ├── index2.js
+    │   └── package.json
+    └── platforms/
+        ├── android/
+        │   ├── AndroidManifest.xml
+        │   └── res/
+        └── ios/
+            └── Info.plist
 ```
 
+* `src`: Putting your source in sub-folder is required for local live sync debugging. Existing plugins should be updated to move their source code in to a subfolder.
 * `index.js`: This file is the CommonJS module which exposes the native API. You can use platform-specific `*.platform.js` files. For example: `index.ios.js` and `index.android.js`. During the plugin installation, the NativeScript CLI will copy the platform resources to the `tns_modules` subdirectory in the correct platform destination in the `platforms` directory of your project.<br/>Alternatively, you can give any name to this CommonJS module. In this case, however, you need to point to this file by setting the `main` key in the `package.json` for the plugin. For more information, see [Folders as Modules](https://nodejs.org/api/modules.html#modules_folders_as_modules).
 * `package.json`: This file contains the metadata for your plugin. It sets the supported runtimes, the plugin name and version and any dependencies. The `package.json` specification is described in detail below.
 * `platforms\android\AndroidManifest.xml`: This file describes any specific configuration changes required for your plugin to work. For example: required permissions. For more information about the format of `AndroidManifest.xml`, see [App Manifest](http://developer.android.com/guide/topics/manifest/manifest-intro.html).<br/>During build, gradle will merge the plugin `AndroidManifest.xml` with the `AndroidManifest.xml` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues.
@@ -93,23 +96,24 @@ NativeScript plugins which contain both native Android and iOS libraries might h
 
 ```
 my-plugin/
-├── ...
-└── platforms/
-    ├── android/
-    │   ├── res/
-    │   ├── MyLibrary.jar
-    │   ├── MyLibrary.aar
-    │   ├── include.gradle
-    │   └── AndroidManifest.xml
-    └── ios/
-        ├── MyiOSFramework.framework
-        ├── build.xcconfig
-        ├── Podfile
-        ├── Info.plist
-        ├── MyStaticiOSLibrary.a
-        └── include/
-            └── MyStaticiOSLibrary/
-                └── ...
+└── src
+    ├── ...
+    └── platforms/
+        ├── android/
+        │   ├── res/
+        │   ├── MyLibrary.jar
+        │   ├── MyLibrary.aar
+        │   ├── include.gradle
+        │   └── AndroidManifest.xml
+        └── ios/
+            ├── MyiOSFramework.framework
+            ├── build.xcconfig
+            ├── Podfile
+            ├── Info.plist
+            ├── MyStaticiOSLibrary.a
+            └── include/
+                └── MyStaticiOSLibrary/
+                    └── ...
 ```
 
 * `platforms\android`: This directory contains any native Android libraries packaged as `*.jar` and `*.aar` packages. These native libraries can reside in the root of this directory or in a user-created sub-directory. During the plugin installation, the NativeScript CLI will configure the Android project in `platforms\android` to work with the plugin.
@@ -194,7 +198,7 @@ tns plugin add <Plugin>
 You can specify a plugin by name in the npm registry, local path or URL. The following are valid values for the `<Plugin>` attribute.
 
 * A `<Name>` or `<Name>@<Version>` for plugins published in the npm registry.
-* A `<Local Path>` to the directory which contains the plugin files and its `package.json` file.
+* A `<Local Path>` to the directory which contains the plugin source files and its `package.json` file.
 * A `<Local Path>` to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.
 * A `<URL>` which resolves to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.
 * A `<git Remote URL>` which resolves to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.