Naming convention docs updated (replaces #553)

README.md

@@ -25,6 +25,17 @@ Refer to our full list of goals for [integrating, packaging, distributing, insta
 
 See the documentation [Table of Contents](docs/readme.md) for an overview of the available documentation for Squirrel.Windows. It includes a [Getting Started Guide](docs/getting-started/0-overview.md) as well as additional topics related to using Squirrel in your applications. 
 
+## Building Squirrel
+For the impatient:
+
+```sh
+git clone https://github.com/squirrel/squirrel.windows
+git submodule update --init --recursive       ## THIS IS THE PART YOU PROBABLY FORGOT
+.\.NuGet\NuGet.exe restore
+msbuild /p:Configuration=Release
+```
+See [Contributing](docs/contributing/contributing.md) for additional information on building and contributing to Squirrel.
+
 
 ## License and Usage
 

docs/readme.md

@@ -35,6 +35,7 @@ The **[Getting Started Guide](getting-started/0-overview.md)** provides a step-b
   * [Machine-wide Installs](using/machine-wide-installs.md) - generating an MSI file suitable for installation via Group Policy.
   * [Debugging Installs](using/debugging-installs.md) - tips for debugging Squirrel.Windows initial installs.
 * **Packaging** - documentation related to packaging app files and preparing them for release.
+  * [Naming Conventions](using/naming.md) - overview of sources used in naming (e.g., shortcut name).
   * [NuGet Package Metadata](using/nuget-package-metadata.md) - overview of the NuGet metadata and its uses by Squirrel.
   * [Squirrel Command Line](using/squirrel-command-line.md) - command line options for `Squirrel --releasify`
   * [Delta Packages](using/delta-packages.md) - an overview of how `Squirrel.exe` creates delta packages.

docs/using/install-process.md

@@ -1,9 +1,9 @@
 | [docs](..)  / [using](.) / install-process.md
 |:---|
 
-# Install Process
-
-This section goes into detail about the install process.
+# Install Process
+
+This section goes into detail about the install process.
 
 ## Setup.exe 
 
@@ -49,7 +49,7 @@ The `Setup.exe` application preforms the following:
 4. **Executes `Update.exe` to Finish Install** - executes the `Updater.exe` application with the `/install` switch to finish the application installation and then launch the application.
     1. **Copy MyApp to `app-1.0.0` Directory** - copy the full version of MyApp files to a application sub-directory (e.g., `MyApp\app-1.0.0`). 
     2. **Launch MyApp** - at the end of the setup process, the Updater launches the  newly installed version of MyApp.
-6. **MyApp Creates Shortcuts** - the first execution of the application will cause shortcuts to be created on the desktop and Windows start menu for MyApp. 
+6. **MyApp Creates Shortcuts** - the first execution of the application will cause shortcuts to be created on the desktop and Windows start menu for MyApp. 
 
 ## Desktop & Windows Start Shortcuts
 
@@ -65,7 +65,8 @@ By default, application shortcuts are created on the desktop and the Windows Sta
 
 * [Loading GIF](loading-gif.md) - specify a "loading" image during initial install of large applications.
 * [Machine-wide Installs](machine-wide-installs.md) - generating an MSI file suitable for installation via Group Policy.
-* [NuGet Package Metadata](using/nuget-package-metadata.md) - overview of the NuGet metadata and its uses by Squirrel.
+* [NuGet Package Metadata](nuget-package-metadata.md) - overview of the NuGet metadata and its uses by Squirrel.
+* [Naming Conventions](naming.md) - A more complete view of how Squirrel names everything.
 
 ---
 | Return: [Table of Contents](../readme.md) |

docs/using/naming.md

@@ -0,0 +1,45 @@
+| [docs](..)  / [using](.) / naming.md
+|:---|
+
+# Naming Conventions
+
+In addition to the [NuGet Package Metadata](nuget-package-metadata.md), there are other places that squirrel pulls naming information from. Here is the logic:
+
+## Shortcut name
+
+The shortcut name is selected from the first non-null item below:
+
+1. `[assembly: AssemblyProduct("MyApp")` (from `AssemblyInfo.cs`)
+2. Squirrel NuGet Package Metadata `title` property.
+3. `[assembly: AssemblyDescription("MyApp")` (from `AssemblyInfo.cs`)
+4. Filename of the Exe (e.g., MyApp)
+
+## Local Install location
+
+The local install location is determined by the `id` in the NuGet package metadata.
+
+* `%LocalAppData%\<NuGet Package ID>`
+
+**Warning:** Using \[dots\] (i.e., "."'s) in your package id will cause issues ([see issue #523](https://github.com/Squirrel/Squirrel.Windows/issues/523)).
+
+## Program and Features Entry
+The entry in the Windows Uninstall is determined as follows: 
+
+* Squirrel NuGet Package Metadata `title` property
+
+## Releases Folder
+
+The `Squirrel --releasify` command will create update packages based on the following:
+
+* `<NuGet Package ID>-<NuGet Package Version>-delta.nupkg`
+* `<NuGet Package ID>-<NuGet Package Version>-full.nupkg`
+
+![](images/naming-releases.png)
+
+## See Also
+
+* [NuGet Package Metadata](nuget-package-metadata.md) - naming from the NuGet Package Metadata perspective.
+
+---
+| Return: [Table of Contents](../readme.md) |
+|----|

docs/using/nuget-package-metadata.md

@@ -5,13 +5,21 @@
 
 Squirrel uses information from your app's EXE as well as the NuGet package Metadata for the setup and uninstall UI.
 
-* **Id** - name of the application (no spaces or [dots](https://github.com/Squirrel/Squirrel.Windows/issues/523)). Used to name the release packages (e.g., **MyApp**-1.0.0-full.nupkg).
+* **Id** - name of the application (**warning:** you must **[avoid using spaces and dots](https://github.com/Squirrel/Squirrel.Windows/issues/523)** in the Id). 
+   * Name of the release packages (e.g., **MyApp**-1.0.0-full.nupkg). 
+   * Local installation directory (e.g., `%LocalAppData%\MyApp`).
 * **Title** - used for the name of the application in the Windows Application Uninstaller.
-* **Version** - version specified in `Properties\Assembly.cs`. Used for naming the release package(e.g., MyApp-**1.0.0**-full.nupkg) as well as describing the version number in the Windows Uninstaller (see screenshot below).
+* **Version** - version specified in `Properties\Assembly.cs`. 
+   * Name of the release package (e.g., MyApp-**1.0.0**-full.nupkg).
+   * Version number in the Windows Uninstaller (see screenshot below).
 * **Icon Url** - url to an icon to be used for the application. Used for the shortcuts and Windows Uninstaller icons.
 
 ![](images/uninstall-app.png)
 
+## See Also
+
+* [Naming Conventions](naming.md) - overview of sources used naming (including those outside of the NuGet Package Metadata).
+
 ---
 | Return: [Table of Contents](../readme.md) |
 |----|