Improve getting started section

docs/getting_started/install.md

@@ -2,47 +2,57 @@
 
 ## Prerequisites
 
-In order to download necessary tools and to install nodecg-io using the CLI you need network access.
+In order to download necessary tools and to install nodecg-io using the CLI you
+need network access.
 
 ### Required Applications
 
 You'll need the following tools:
 
 -   [Git](https://git-scm.com)
--   [Node.JS](https://nodejs.org/en/) v12.0.0 or newer
--   [Npm](https://www.npmjs.com/get-npm) 7.0.0 or newer
+-   [Node.js](https://nodejs.org/en/) v12.0.0 or newer
+-   [npm](https://www.npmjs.com/get-npm) 7.0.0 or newer
 -   [NodeCG](https://nodecg.dev/) 1.4.0 or newer (1.7.0 or higher recommended)
 
 ### Native Build Tools
 
-Some services depend on packages that require native build tools. You _ONLY_ need to install these if you want to use a service that depends on native modules or if you want to install a development version.
+Some services depend on packages that require native build tools. You _ONLY_
+need to install these if you want to use a service that depends on native
+modules or if you want to install a development version.
 
-The services that require these include StreamDeck, Midi and Serial. Please note that this list might not be up-to-date.
+The services that require these include StreamDeck, Midi and Serial. Please note
+that this list might not be up-to-date.
 
-Here's how to install the native build tools on the most popular operating systems, if you need them:
+Here's how to install the native build tools on the most popular operating
+systems, if you need them:
 
 #### Windows
 
-For Windows, you'll need the Visual Studio Build Tools, if you have Visual Studio installed you should already have them.
-If you don't have Visual Studio just install the Visual Studio Build Tools by running the following command as an **Administrator**:
+For Windows, you'll need the Visual Studio Build Tools, if you have Visual
+Studio installed you should already have them. If you don't have Visual Studio
+just install the Visual Studio Build Tools by running the following command as
+an **Administrator**:
 
 ```shell
 npm install -g windows-build-tools
 ```
 
 #### Linux
 
-For Linux, you'll need a C++ compiler and some other packages. On Ubuntu/Debian based operating systems run the following command:
+For Linux, you'll need a C++ compiler and some other packages. On Ubuntu/Debian
+based operating systems run the following command:
 
 ```shell
 sudo apt install build-essential libusb-1.0-0-dev libasound2-dev libudev-dev
 ```
 
-For other Linux distros you'll need the corresponding packages, just search on the internet how the packages are named for your specific distro.
+For other Linux distros you'll need the corresponding packages, just search on
+the internet how the packages are named for your specific distro.
 
 #### macOS
 
-For macOS, you'll need the Xcode command line tools. To install them run the following command:
+For macOS, you'll need the Xcode command line tools. To install them run the
+following command:
 
 ```shell
 xcode-select --install
@@ -56,33 +66,119 @@ Install the nodecg-io CLI using the following command:
 npm install -g nodecg-io-cli
 ```
 
-_Note:_ If you are running on Linux, you may need to use `sudo` if your npm installation uses a non-writeable path (default on Ubuntu apt packages, usually does not apply to packages installed using [nvm](https://github.com/nvm-sh/nvm))
+_Note:_ If you are running on Linux, you may need to use `sudo` if your npm
+installation uses a non-writeable path (default on Ubuntu apt packages, usually
+does not apply to packages installed using [nvm](https://github.com/nvm-sh/nvm))
 
 ## Install nodecg-io using the nodecg-io CLI
 
-With the nodecg-io CLI installed you can run this command inside a nodecg installation to install nodecg-io:
+> nodecg-io will always be installed into a `nodecg-io/` directory inside your
+> NodeCG installation so that your bundles and all bundles from nodecg-io are
+> separated. The CLI will add this path to the loaded bundles in your NodeCG
+> configuration automatically, you don't need to worry about it.
+
+With the nodecg-io CLI installed you can run this command inside a NodeCG
+installation to install nodecg-io:
 
 ```shell
-nodecg-io install
+$ nodecg-io install
+Installing nodecg-io...
 ```
 
-You will get a prompt which asks you which version you want to install.
-
--   By selecting an actual version (e.g., `0.1`) you create a production install that downloads the required packages from npm and setups a npm workspace to install all dependencies. Here you can choose which services you want to install.
-
--   By selecting `development` you create a development install that clones the nodecg-io git repo and builds everything from scratch. We only recommend a dev install if you are sure that you want to contribute to nodecg-io. Here you always must install all services.
-
-For starters, we recommend using the latest non-development version.
-
-nodecg-io will always be installed into a `nodecg-io/` directory inside your nodecg installation so that your bundles and all bundles from nodecg-io are separated. The CLI will add this path to the loaded bundles in your nodecg configuration automatically, you don't need to worry about it.
-
-If you want to every change your nodecg-io installation to add/remove a service or change the version, you can always re-run `nodecg-io install`. If a nodecg-io installation is found, its options will be preselected in the prompt. Re-running `nodecg-io install` will also update all packages to the latest patch version, if you have a production installation, and pull the repository and rebuild, if you have a development installation.
-
-## Start nodecg
-
-When starting nodecg you should see that all nodecg-io related bundles should be loaded and that you can now access nodecg-io in your nodecg dashboard.
-
-Now you can either install an already existing bundle that uses nodecg-io, [create a new bundle](./create_new_bundle.md) or [integrate an existing bundle](./existing_bundle.md).
+You will get a prompt which asks you which version you want to install:
+
+<pre><b><span style="color:#1cdc9a">user@computer</span>:<span   style="color:#3daee9">~/nodecg</span></b>$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+<span style="color:#11d116">?</span> <b>Which version do you want to install?</b> (Use arrow keys) 
+  development 
+<span style="color:#1abc9c">❯ 0.1</span></pre>
+
+There are two possible installation types:
+
+-   By selecting an actual version (e.g., `0.1`) you create a production install
+    that downloads the required packages from npm and setups a npm workspace to
+    install all dependencies. Here you can choose which services you want to
+    install. Here you can not easily install our premade examples.
+
+-   By selecting `development` you create a development install that clones the
+    nodecg-io git repo and builds everything from scratch. We only recommend a
+    development install if you are sure that you want to contribute to nodecg-io
+    or want to try an included example. Here you always must install all
+    services and examples.
+
+For starters, we recommend using the development version, so you may try our
+premade examples.
+
+### Production install
+
+<details>
+  <summary>Click to see more!</summary>
+
+Because you selected a production install you may select the services to be
+included in this next step:
+
+<pre><b><span style="color:#1cdc9a">user@computer</span>:<span style="color:#3daee9">~/nodecg</span></b>$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+<span style="color:#11d116">?</span> <b>Which version do you want to install?</b> <span style="color:#1abc9c">0.1</span>
+<span style="color:#11d116">?</span> <b>Which services do you want to use?</b> (Press <span style="color:#16a085">&lt;space&gt;</span> to select, <span    style="color:#16a085">&lt;a&gt;</span> to toggle all,
+<span style="color:#16a085">&lt;i&gt;</span> to invert selection, and <span style="color:#16a085">&lt;enter&gt;</span> to proceed)
+<span style="color:#1abc9c">❯◯ ahk</span>
+ ◯ android
+ ◯ curseforge
+ ◯ discord
+ ◯ intellij
+ ◯ irc
+ ◯ midi-input
+(Move up and down to reveal more choices)</pre>
+
+If you want to every change your nodecg-io installation to add/remove a service
+or change the version, you can always re-run `nodecg-io install`. If a nodecg-io
+installation is found, its options will be preselected in the prompt. Re-running
+`nodecg-io install` will also update all packages to the latest patch version.
+
+</details>
+
+### Development install
+
+<details>
+  <summary>Click to see more!</summary>
+
+Because you selected a production install you may select to use the samples and
+documentation to be included in these next steps:
+
+<pre><b><span style="color:#1cdc9a">user@computer</span>:<span style="color:#3daee9">~/nodecg</span></b>$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+<span style="color:#11d116">?</span> <b>Which version do you want to install?</b> <span style="color:#1abc9c">development</span>
+<span style="color:#11d116">?</span> <b>Would you like to use the provided samples?</b> (y/N) </pre>
+
+<pre><b><span style="color:#1cdc9a">user@computer</span>:<span style="color:#3daee9">~/nodecg</span></b>$ nodecg-io install
+Installing nodecg-io...
+Detected nodecg installation at /home/user/nodecg.
+<span style="color:#11d116">?</span> <b>Which version do you want to install?</b> <span style="color:#1abc9c">development</span>
+<span style="color:#11d116">?</span> <b>Would you like to use the provided samples?</b> <span style="color:#1abc9c">No</span>
+<span style="color:#11d116">?</span> <b>Would you like to clone the documentation?</b> (y/N) </pre>
+
+If you want to every change your nodecg-io installation to add/remove a service
+or change the version, you can always re-run `nodecg-io install`. If a nodecg-io
+installation is found, its options will be preselected in the prompt. Re-running
+`nodecg-io install` will also pull the repository and rebuild it.
+
+</details>
+
+### Continue reading
+
+There are many example bundles premade for most services, so you may take a look
+at the
+[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide (It
+will also tell you how to start NodeCG, log in and how to use the GUI). Or you
+could directly take a deep dive into our framework and either
+[create a new bundle](./create_new_bundle.md) or
+[integrate an existing bundle](./existing_bundle.md). There are other bundles
+using nodecg-io, witch you could try, so may take a look around GitHub or
+GitLab.
 
 ## Uninstall nodecg-io
 
@@ -92,4 +188,5 @@ If you want to uninstall nodecg-io you can run the following command:
 nodecg-io uninstall
 ```
 
-This will remove the `nodecg-io` directory inside your nodecg installation and also will remove it from the loaded bundle paths in your nodecg configuration.
+This will remove the `nodecg-io` directory inside your NodeCG installation and
+also will remove it from the loaded bundle paths in your NodeCG configuration.

docs/getting_started/try_example_bundle.md

@@ -0,0 +1,124 @@
+# Try an included sample
+
+Trying one of the premade example bundles is a good way to get to know the
+framework and especially the selected service.
+
+> In case you installed the **production** branch of nodecg-io, you are out of
+> luck. Because the build process will cause problems if you just take one of
+> the samples and rebuild elsewhere.
+
+If you installed **dev** branch via the `nodecg-io-cli` and did not select the
+“use the samples”-option run `nodecg-io install` and select it.
+
+In case you cloned the repository directly from GitHub, everything should be
+included. But you may want to pull recent changes and rebuild the project.
+
+## Step 1: Run NodeCG
+
+Now you need to start NodeCG. There are a couple of different ways to do this:
+
+### Using VS Code
+
+If you have nodecg-io open in your VS Code instance, you can launch NodeCG using
+the `Run and Debug` Explorer View:
+
+![Run and Debug Explorer View](../assets/run_from_vscode.png)
+
+### Using the terminal
+
+You may also launch NodeCG using your terminal with:
+
+<pre><b><span style="color:#1cdc9a">user@computer</span>:<spanstyle="color:#3daee9">~/nodecg</span></b>$ npm run start
+
+> [email protected] start
+> node index.js
+
+info: [nodecg/lib/server] Starting NodeCG 1.8.1 (Running on Node.js v16.11.1)
+info: [nodecg-io-core] Minzig!
+
+// A whole host of logging output
+
+info: [nodecg/lib/server] NodeCG running on http://localhost:9090</pre>
+
+Now you can open the NodeCG dashboard (by default) under
+<http://localhost:9090>.
+
+## Step 2: Log in to nodecg-io
+
+Now navigate to the `nodecg-io` tab in the NodeCG dashboard.
+
+If you are logging in for the first time you will have to set your password.
+
+![Log in screen](../assets/log_in_screen.png)
+
+Else you simply have to log in with your previously chosen password.
+
+Now you are looking at the `nodecg-io` config menu. It should look like this:
+
+![`nodcg-io` config menu](../assets/nodcg-io-dashboard.png)
+
+## Step 3: Learning how to use the GUI
+
+The current GUI is just intended to make the project usable, but it is not very
+user-friendly. As a more long term solution, a new GUI will be developed that
+also focuses on user experience. Until the new GUI is developed, you will have
+to arrange yourself with this one. So, to get started:
+
+![`nodcg-io` colour coded](../assets/nodcg-io-colored.png)
+
+### In <span style="color:#b06770">pink</span>: NodeCG Tabs
+
+Here you will find every NodeCG-bundle that has a dashboard. Here you may select
+the [`nodecg-io-debug`](../samples/debug.md)-dashboard, if it is installed.
+
+### In <span style="color:#b6b61c">yellow</span>: Monaco editor
+
+It is basically only a text editor which is used to save configurations for
+service instances.
+
+### In <span style="color:#21885c">green</span>: Services section
+
+Here you may create, update and delete instances of a service. Each instance has
+its own name and configuration. The menu will expand depending on the option
+selected in the first dropdown.
+
+_Creating a new service instance_:
+
+This can be accomplished by selecting the item `'New'`. Then a new dropdown will
+be revealed, in witch you may select the service type. Additionally, you must
+select an instance name. Then click `'Create'`. The newly created instance
+should be selected.
+
+_Configure a service instance_:
+
+While a supported service instance is selected, you may change the config in
+monaco, then click `'Save'`.
+
+_Deleting a service instance_:
+
+This can be accomplished by selecting an existing instance. Then click
+`'Delete Instance'`.
+
+### In <span style="color:#69318e">violet</span>: Bundles section
+
+This section has three dropdowns:
+
+1. Bundle: Here you can select a bundle to configure.
+2. Service: If this bundle uses more than one service, you may select the
+   service to set or unset here.
+3. Service Instance: Here you can select one instance of the service type set at
+   2 or `none`.
+
+### In <span style="color:#b71424">red</span>: Unset all Button
+
+This button will set the service instance for every bundle/service combination
+to none, effectively removing the access to every service from all bundles.  
+**Caution**: This can not be undone, and you will have to set up all the bundles
+again. _The service instances will be unaffected._
+
+## Step 4: Configure the sample
+
+The configurations for every sample bundle differ too greatly from each other to
+be included here, so you have to take a look at the documentation for your
+sample bundle. You will find it on the left-hand side of this page in the
+category `Services`.

docs/samples/ahk.md

@@ -1,25 +1,24 @@
-## Using the AHK sample bundle
+## Using the AutoHotkey sample bundle
 
-The AHK sample bundle in `samples/ahk-sendcommand` shows how to send a command to a HotkeylessAHK server.
+The AutoHotkey sample bundle in `samples/ahk-sendcommand` shows how to send a
+command to a HotkeylessAHK server.
 
 ### Prerequisites
 
--   Working NodeCG & nodecg-io installation
--   A running [HotkeylessAHK](https://github.com/sebinside/HotkeylessAHK) setup.
-
-### Configure the ahk sample bundle
-
-1. Start nodecg with nodecg-io installed. The ahk bundle is currently part of it, so it should also be loaded.
+You will need a working `nodecg-io` installation. If you have non yet take a
+look at [installation guide](../getting_started/install.md). You may need to
+install this bundle, so take a look at the
+[“Try an included sample”](../getting_started/try_example_bundle.md)-Guide. It
+will also tell you how to log in and how to use the GUI.
 
-2. Go to the `nodecg-io` tab in the nodecg dashboard.
+**You also need:**
 
-3. Login using your password. If this is your first run, then enter the password with which you want to encrypt your configurations and credentials.
-
-4. Create a new ahk service instance using the left upper menu.
+-   A running [HotkeylessAHK](https://github.com/sebinside/HotkeylessAHK) setup.
 
-5. Enter the host and port of the HotkeylessAHK Server.
+### Configure the AutoHotkey sample bundle
 
-    The created instance should be automatically selected, if not select it in the upper left menu. Enter your host and port in monaco (the text-editor on the right) in this format:
+1. In NodeCG, create a new ahk service instance.
+2. Enter the host and port of the HotkeylessAHK Server:
 
     ```json
     {
@@ -30,6 +29,6 @@ The AHK sample bundle in `samples/ahk-sendcommand` shows how to send a command t
 
     After entering it, click save.
 
-6. Set the created ahk service instance to the service dependency of the ahk bundle.
-
-7. A small window with the text “Hello World” should have popped up.
+3. Set the sample's (`ahk-sendcommand`) dependency to be the newly created
+   service instance (of type `ahk`).
+4. A small window with the text “Hello World” should have popped up.