chore: intro cleanup and npm package doc notes

Author: NathanWalker

introduction.md

@@ -18,7 +18,15 @@ The docs have been written with no assumtions of the readers experience, however
 - [Introduction to JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 - [Re-Introduction to JavaScript to refresh your knowledge](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript)
 
-## Templates
+## [Environment Setup](environment-setup)
+
+You will want to setup your development machine using the [Environment Setup guide here](environment-setup) which involves preparing your machine for iOS and Android development as well as installing the [NativeScript CLI](https://www.npmjs.com/package/nativescript) via `npm install -g nativescript`
+
+## Overview of NativeScript development
+
+:::warning Note
+The following is a general overview of NativeScript development. To try any of the commands mentioned be sure you have a proper environment setup first.
+:::
 
 NativeScript allows scaffolding projects with various templates to kickstart your app development. Official templates can be found in the [Templates GitHub repository](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages) and on [NPM](https://www.npmjs.com/search?q=%40nativescript%20template).
 
@@ -372,9 +380,3 @@ NavigationButton {
 - [Read JavaScript App Template Style Guide](https://github.com/NativeScript/nativescript-starter-kits-utils/blob/master/docs/style-guide-app-template.md)
 
 - [Read Angular App Template Style Guide](https://github.com/NativeScript/nativescript-starter-kits-utils/blob/master/docs/style-guide-app-template-ng.md)
-
-## Versioning Scheme
-
-`@nativescript/core` does not follow Semantic Versioning. Major framework releases are released every six months (~March and ~September), while minor and patch releases may be released as often as every week. Patch releases should never contain breaking changes, however minor, and major releases can. We strive to note any breaking changes in the Changelogs, to make upgrades as easy as possible.
-
-When referencing the `@nativescript/core` package, you should use a fixed version constraint such as `7.0.11`, or alternatively `~7.0.11` to allow installing patch updates.

understanding-packages.md

@@ -2,30 +2,42 @@
 title: Understanding @nativescript
 ---
 
-There are a few npm packages that are fundamental to NativeScript development and are good to understand.
+There are a few npm packages that are fundamental to NativeScript development and good to understand.
 
-### `@nativescript/core`
+### [@nativescript/core](https://www.npmjs.com/package/@nativescript/core)
 
 A JavaScript library providing an easy to use api for interacting with iOS and Android platform APIs.
 
-### `@nativescript/android`
+### [@nativescript/android](https://www.npmjs.com/package/@nativescript/android)
 
 The v8 JavaScript engine runtime enabled for Android NativeScript development.
 
-### `@nativescript/ios`
+### [@nativescript/ios](https://www.npmjs.com/package/@nativescript/ios)
 
 The v8 JavaScript engine runtime enabled for iOS NativeScript development.
 
 You can also use a [JavaScriptCore](https://developer.apple.com/documentation/javascriptcore) version of this runtime using the npm tag `JSC`. This can be useful for projects that may experience any issue with the v8 engine.
 
-### `@nativescript/types`
+### [@nativescript/types](https://www.npmjs.com/package/@nativescript/types)
 
 This provides TypeScript definitions for all iOS and Android APIs available to do NativeScript development with.
 
-### `@nativescript/webpack`
+### [@nativescript/webpack](https://www.npmjs.com/package/@nativescript/webpack)
 
 This provides loaders, helpers and base configs for all fundamental NativeScript development to debug, run, build and release your apps.
 
+### [nativescript](https://www.npmjs.com/package/nativescript)
+
+CLI (Command Line Interface) used for creating/running/building/deploying NativeScript apps. Often installed globally along with a proper [Environment Setup](environment-setup) via `npm install -g nativescript`.
+
 ## Plugins
 
 There are also quite a number of plugins maintained and developed by the NativeScript TSC which you can find [documented here](plugins/index)
+
+## NPM Versioning
+
+NativeScript packages do not follow Semantic Versioning for a particular reason. Since NativeScript enables the empowerment of JavaScript with native platform APIs we strive to do major releases around platform API tooling upgrade cycles (Things like Xcode, Android Studio, etc.). Major framework releases are generally released every six months (~March and ~September which is often the timeframe platform API toolchains are also updated), while minor and patch releases may be released as often as every week. Patch releases should never contain breaking changes, however minor, and major releases can. We strive to note any breaking changes in the Changelogs, to make upgrades as easy as possible.
+
+We always recommend using `~` (tilda) with any NativeScript package versions in your projects as that will ensure anytime you execute a `ns clean` against your project that the next run will pull down the latest patch release fixes to anything we may have released.
+
+For example, when referencing the `@nativescript/core` package, you could use a fixed version constraint such as `8.0.0`, or alternatively `~8.0.0` to allow installing patch updates automatically after a project clean.