chore: improve documentation around First Start (Sofie-Automation#1576)

Author: jstarpl

packages/documentation/docs/for-developers/device-integrations/intro.md

@@ -1,6 +1,6 @@
 # Introduction
 
-Device integrations in Sofie are part of the Timeline State Resolver (TSR) library. A device integration has a couple of responsibilites in the Sofie eco system. First and foremost it should establish a connection with a foreign device. It should also be able to convert Sofie's idea of what the device should be doing into commands to control the device. And lastly it should export interfaces to be used by the blueprints developer.
+Device integrations in Sofie are part of the Timeline State Resolver (TSR) library. A device integration has a couple of responsibilities in the Sofie eco-system. First and foremost it should establish a connection with a foreign device. It should also be able to convert Sofie's idea of what the device should be doing into commands to control the device. And lastly it should export interfaces to be used by the blueprints developer.
 
 In order to understand all about writing TSR integrations there are some concepts to familiarise yourself with, in this documentation we will attempt to explain these.
 

packages/documentation/docs/for-developers/for-blueprint-developers/intro.md

@@ -8,13 +8,30 @@ sidebar_position: 1
 Documentation for this page is yet to be written.
 :::
 
-[Blueprints](../../user-guide/concepts-and-architecture.md#blueprints) are programs that run inside Sofie Core and interpret
-data coming in from the Rundowns and transform that into playable elements. They use an API published in [@sofie-automation/blueprints-integration](https://sofie-automation.github.io/sofie-core/typedoc/modules/_sofie_automation_blueprints_integration.html) library to expose their functionality and communicate with Sofie Core.
+[Blueprints](../../user-guide/concepts-and-architecture.md#blueprints) are JavaScript programs that run inside Sofie Core and interpret data coming in from the Rundowns and transform that into playable elements. They use an API published in [@sofie-automation/blueprints-integration](https://sofie-automation.github.io/sofie-core/typedoc/modules/_sofie_automation_blueprints_integration.html) [TypeScript](https://www.typescriptlang.org/) library to expose their functionality and communicate with Sofie Core.
 
 Technically, a Blueprint is a JavaScript object, implementing one of the `BlueprintManifestBase` interfaces.
 
+Sofie doesn't have a built-in package manager or import, so all dependencies need to be bundled into a single `*.js` file bundle using a bundler such as  [Rollup](https://rollupjs.org/) or [webpack](https://webpack.js.org/). The community has built a set of utilities called [SuperFlyTV/sofie-blueprint-tools](https://github.com/SuperFlyTV/sofie-blueprint-tools/) that acts as a nascent framework for building & bundling Blueprints written in TypeScript.
+
+:::info
+Note that the Runtime Environment for Blueprints in Sofie is plain JavaScript at [ES2015 level](https://en.wikipedia.org/wiki/ECMAScript_version_history#6th_edition_%E2%80%93_ECMAScript_2015), so other ways of building Blueprints are also possible.
+:::
+
 Currently, there are three types of Blueprints:
 
 - [Show Style Blueprints](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie_automation_blueprints_integration.ShowStyleBlueprintManifest.html) - handling converting NRCS Rundown data into Sofie Rundowns and content.
 - [Studio Blueprints](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie_automation_blueprints_integration.StudioBlueprintManifest.html) - handling selecting ShowStyles for a given NRCS Rundown and assigning NRCS Rundowns to Sofie Playlists
 - [System Blueprints](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie_automation_blueprints_integration.SystemBlueprintManifest.html) - handling system provisioning and global configuration
+
+# Show Style Blueprints
+
+These blueprints interpret the data coming from the [NRCS](../../user-guide/installation/installing-a-gateway/rundown-or-newsroom-system-connection/intro.md), meaning that they need to support the particular data structures that a given Ingest Gateway uses to store incoming data from the Rundown editor. They will need to convert Rundown Pages, Cues, Items, pieces of show script and other types of objects into [Sofie concepts](../concepts-and-architecture.md) such as Segments, Parts, Pieces and AdLibs.
+
+# Studio Blueprints
+
+These blueprints provide a "baseline" Timeline that is being used by your Studio whenever there isn't a Rundown active. They also handle combining Rundowns into RundownPlaylists. Via the [`applyConfig`](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie-automation_blueprints-integration.StudioBlueprintManifest.html#applyconfig) method, these Blueprints enable a _Configuration-as-Code_ approach to configuring connections to various elements of your Control Room and Studio.
+
+# System Blueprints
+
+These blueprints exist to allow a _Configuration-as-Code_ approach to an entire Sofie system. This is done via the [`applyConfig`](https://sofie-automation.github.io/sofie-core/typedoc/interfaces/_sofie-automation_blueprints-integration.SystemBlueprintManifest.html#applyconfig) providing personality information such as global system configuration or system-wide HotKeys via the Blueprints.

packages/documentation/docs/user-guide/concepts-and-architecture.md

@@ -157,7 +157,7 @@ Another benefit of basing the playout on a timeline is that when programming the
 ### How does it work?
 
 :::tip
-Fun tip! The timeline in itself is a [separate library available on github](https://github.com/SuperFlyTV/supertimeline).
+Fun tip! The timeline in itself is a [separate library available on GitHub](https://github.com/SuperFlyTV/supertimeline).
 
 You can play around with the timeline in the browser using [JSFiddle and the timeline-visualizer](https://jsfiddle.net/nytamin/rztp517u/)!
 :::

packages/documentation/docs/user-guide/configuration/settings-view.md

@@ -167,7 +167,7 @@ Clicking on the action and filter pills allows you to edit the action parameters
 
 ##### Shift Registers
 
-Shift Register modification actions are a special type of an Action, that modifies an internal state memory of the [Input Gateway](../installation/installing-input-gateway.md) and allows combination triggers, pagination, etc. on devices that don't natively support them or combining multiple devices into a single Control Surface. Refer to _Input Gateway_ documentation for more information on Shift Registers.
+Shift Register modification actions are a special type of an Action, that modifies an internal state memory of the [Input Gateway](../installation/installing-a-gateway/input-gateway.md) and allows combination triggers, pagination, etc. on devices that don't natively support them or combining multiple devices into a single Control Surface. Refer to _Input Gateway_ documentation for more information on Shift Registers.
 
 Shift Register actions have no effect in the browser, triggered from a _Hotkey_.
 

packages/documentation/docs/user-guide/features/intro.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 1
+---
+# Introduction
+
+This section documents the user-facing features of Sofie, that is: what is visible in the User Interface when connected to the Sofie Web App. For more information about the playout features of Sofie, see the [For Blueprint Developers](../../for-developers/for-blueprint-developers/intro) section.
+
+The _Rundowns_ view will display all the active rundowns that the _Sofie Core_ has access to. 
+
+![Rundown View](/img/docs/getting-started/rundowns-in-sofie.png)
+
+The _Status_ view displays the current status for the attached devices and gateways.
+
+![Status View – Describes the state of _Sofie Core_](/img/docs/getting-started/status-page.jpg)
+
+The _Settings_ view contains various settings for the Studio, Show Styles, Blueprints etc. If the link to the settings view is not visible in your application, check your [Access Levels](access-levels.md). More info on specific parts of the _Settings_ view can be found in their corresponding guide sections. 
+
+![Settings View – Describes how the _Sofie Core_ is configured](/img/docs/getting-started/settings-page.jpg)

packages/documentation/docs/user-guide/installation/initial-sofie-core-setup.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 3
+sidebar_position: 30
 ---
 
 # Initial Sofie Core Setup
 
 #### Prerequisites
 
-* [Installed and running _Sofie Core_](installing-sofie-server-core.md)
+* [Installed and running _Sofie Core_](quick-install.md)
 
 Once _Sofie Core_ has been installed and is running you can begin setting it up. The first step is to navigate to the _Settings page_. Please review the [Sofie Access Level](../features/access-levels.md) page for assistance getting there.
 

packages/documentation/docs/user-guide/installation/installing-a-gateway/_category_.json

@@ -1,4 +1,4 @@
 {
     "label": "Installing a Gateway",
-    "position": 5
+    "position": 50
 }

…installation/installing-input-gateway.md …on/installing-a-gateway/input-gateway.mdpackages/documentation/docs/user-guide/installation/installing-input-gateway.md renamed to packages/documentation/docs/user-guide/installation/installing-a-gateway/input-gateway.md packages/documentation/docs/user-guide/installation/installing-input-gateway.md renamed to packages/documentation/docs/user-guide/installation/installing-a-gateway/input-gateway.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 40
+---
+
 # Input Gateway
 
 The Input Gateway handles control devices that are not capable of running a Web Browser. This allows Sofie to integrate directly with devices such as: Hardware Panels, GPI input, MIDI devices and external systems being able to send an HTTP Request.
@@ -31,14 +35,18 @@ Currently, input gateway supports:
 
 ### Shift Registers
 
-Input Gateway supports the concept of _Shift Registers_. A Shift Register is an internal variable/state that can be modified using Actions, from within [Action Triggers](../configuration/settings-view.md#actions). This allows for things such as pagination, _Hold Shift + Another Button_ scenarios, and others on input devices that don't support these features natively. _Shift Registers_ are also global for all devices attached to a single Input Gateway. This allows combining multiple Input devices into a single Control Surface.
+Input Gateway supports the concept of _Shift Registers_. A Shift Register is an internal variable/state that can be modified using Actions, from within [Action Triggers](../../configuration/settings-view.md#actions). This allows for things such as pagination, _Hold Shift + Another Button_ scenarios, and others on input devices that don't support these features natively. _Shift Registers_ are also global for all devices attached to a single Input Gateway. This allows combining multiple Input devices into a single Control Surface.
 
 When one of the _Shift Registers_ is set to a value other than `0` (their default state), all triggers sent from that Input Gateway become prefixed with a serialized state of the state registers, making the combination of a _Shift Registers_ state and a trigger unique.
 
 If you would like to have the same trigger cause the same action in various Shift Register states, add multiple Triggers to the same Action, with different Shift Register combinations.
 
 Input Gateway supports an unlimited number of Shift Registers, Shift Register numbering starts at 0.
 
+### AdLib Tally
+
+Starting with version 0.5.0, Input Gateway can show additional information about the playout state of AdLibs. Select device integrations within Input Gateway support _Styles_ which allow elements of the HID devices to be specifically styled. These Style classes are matched with [Action Triggers](../../configuration/settings-view.md#action-triggers) using Style class names. You can configure additional _Style classes_ for when a given AdLib is "active" (currently playing) or "next" (i.e. will be playing after a take) appending a suffix `:active` and `:next` to a Style class name.
+
 ### Further Reading
 
 - [Input Gateway Releases on GitHub](https://github.com/Sofie-Automation/sofie-input-gateway/releases)

packages/documentation/docs/user-guide/installation/installing-a-gateway/intro.md

@@ -1,25 +1,41 @@
 ---
 sidebar_label: Introduction
-sidebar_position: 1
+sidebar_position: 10
 ---
 # Introduction: Installing a Gateway
 
 #### Prerequisites
 
-* [Installed and running Sofie Core](../installing-sofie-server-core.md)
+* [Installed and running Sofie Core](../quick-install.md)
 
-The _Sofie Core_ is the primary application for managing the broadcast, but it doesn't play anything out on it's own. A Gateway will establish the connection from _Sofie Core_ to other pieces of hardware or remote software. A basic setup may include the [Spreadsheet Gateway](rundown-or-newsroom-system-connection/installing-sofie-with-google-spreadsheet-support.md) which will ingest a rundown from Google Sheets then, use the [Playout Gateway](playout-gateway.md) send commands to a CasparCG Server graphics playout, an ATEM vision mixer, and / or the [Sisyfos audio controller](https://github.com/olzzon/sisyfos-audio-controller).
+The _Sofie Core_ is the primary application for managing the broadcast, but it doesn't play anything out on it's own. A Gateway will establish the connection from _Sofie Core_ to other pieces of hardware or remote software. A basic setup may include the [Spreadsheet Gateway](rundown-or-newsroom-system-connection/google-spreadsheet.md) which will ingest a rundown from Google Sheets then, use the [Playout Gateway](playout-gateway.md) send commands to a CasparCG Server graphics playout, an ATEM vision mixer, and / or the [Sisyfos audio controller](https://github.com/olzzon/sisyfos-audio-controller).
 
+<!-- 
 Installing a gateway is a two part process. To begin, you will [add the required Blueprints](../installing-blueprints.md), or mini plug-in programs, to _Sofie&nbsp;Core_ so it can manipulate the data from the Gateway. Then you will install the Gateway itself. Each Gateway follows a similar installation pattern but, each one does differ slightly. The links below will help you navigate to the correct Gateway for the piece of hardware / software you are using.
+-->
 
-### Rundown & Newsroom Gateways
+Setting up a gateway (also called Peripheral Device) from scratch generally is a five-step process:
+1. Start the executable image and have it connect to Sofie Core
+2. Assign the new Peripheral Device to a Studio
+3. Configure the gateway inside the Sofie user interface, configure *sub-devices* \(MOS primary & secondary, video mixers, playout servers, HMI devices\) if applicable
+4. Restart the gateway to apply the new settings
+5. Verify connection on the *Status* page in Sofie
+
+:::tip
+You can expect the initial connection in Step 1 to fail. This is expected. Peripheral Devices cannot be connected to Sofie unless they are assigned to a Studio. This initial connection is required to inform Sofie about the capabilities of the gateway and set up authorization tokens that will be expected by Sofie in subsequent connections. Do not be discouraged by the gateway shutting down or restarting and just follow the steps above as described.
+:::
 
-* [Google Spreadsheet Gateway](rundown-or-newsroom-system-connection/installing-sofie-with-google-spreadsheet-support.md)
-* [iNEWS Gateway](rundown-or-newsroom-system-connection/inews-gateway.md)
-* [MOS Gateway](rundown-or-newsroom-system-connection/mos-gateway.md)
+### Gateways and their types and functions
 
-### Playout & Media Manager Gateways
+* [Playout Gateway](playout-gateway.md) - sends commands and modifies the state of devices in your Control Room and Studio: video servers, mixers, LED screens, lighting controllers & graphics systems
+* [Package Manager](../installing-package-manager.md) - checks if media required for a successful production is where it should be, produces proxy versions for preview inside of Rundown View, does quality control of the media and provides feedback to the Blueprints and the User
+* [Input Gateway](input-gateway.md) - receives signals from and provides support for *Human Interface Devices* devices such as Stream Decks, Skaarhoj panels and MIDI devices
+* Live Status Gateway - provides support for external services that would like to know about the state of a Studio in Sofie, incl. currently playing Parts and Pieces, available AdLibs, etc.
+
+### Rundown & Newsroom Gateways
 
-* [Playout Gateway](playout-gateway.md)
-* [Media Manager](../media-manager.md)
+* [Google Spreadsheet Gateway](rundown-or-newsroom-system-connection/google-spreadsheet.md) - supports creating Rundowns inside of Google Spreadsheet cloud service
+* [iNEWS Gateway](rundown-or-newsroom-system-connection/inews-gateway.md) - integrates with Avid iNEWS via FTP
+* [MOS Gateway](rundown-or-newsroom-system-connection/mos-gateway.md) - integrates with MOS-compatible NRCS systems (AP ENPS, CGI OpenMedia, Octopus Newsroom, Saga, among others)
+* [Rundown Editor](../rundown-editor.md) - a minimal, self-contained Rundown creation utility
 

packages/documentation/docs/user-guide/installation/installing-a-gateway/playout-gateway.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 30
 ---
 # Playout Gateway