DOCS: Clarified workflows section including page naming, guidance, pros and cons. (ISX-1857) (#1895)

* ISX-1857 - Clarified workflows section including page naming, guidance, pros and cons.

* whitespace formatting fix

* ISX-1880 updates to playerinput component and workflow pages

* Update Workflow-PlayerInput.md

addressed PR comment

Author: duckets

Packages/com.unity.inputsystem/Documentation~/PlayerInput.md

@@ -26,9 +26,9 @@ There are a few options for doing exactly how the Player Input component does th
 
 ### Handling local multiplayer scenarios
 
-You can also use multiple **Player Input** components (each on a separate instance of a prefab) along with the [**Player Input Manager**](PlayerInputManager.md) component to implement local multiplayer features, such as player lobbies, device filtering, and screen-splitting.
+You can also have multiple **Player Input** components active at the same time (each on a separate instance of a prefab) along with the [**Player Input Manager**](PlayerInputManager.md) component to implement local multiplayer features, such as device filtering, and screen-splitting.
 
-In these local multiplayer scenarios, the Player Input component should be on a prefab which the [**Player Input Manager**](PlayerInputManager.md) has a reference to. The **Player Input Manager** then instantiates players as they join the game and pairs each player instance to a unique device that the player uses exclusively (for example, one gamepad for each player). You can also manually pair devices in a way that enables two or more players to share a Device (for example, left/right keyboard splits or hot seat use).
+In these local multiplayer scenarios, the Player Input component should be on a prefab that represents a player in your game, which the [**Player Input Manager**](PlayerInputManager.md) has a reference to. The **Player Input Manager** then instantiates players as they join the game and pairs each player instance to a unique device that the player uses exclusively (for example, one gamepad for each player). You can also manually pair devices in a way that enables two or more players to share a Device (for example, left/right keyboard splits or hot seat use).
 
 Each `PlayerInput` corresponds to one [`InputUser`](UserManagement.md). You can use [`PlayerInput.user`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_user) to query the `InputUser` from the component.
 
@@ -62,7 +62,7 @@ The simplest workflow is to use the project-wide actions defined in the [Input A
 
 #### Enabling and disabling Actions
 
-The Player Input component automatically handles enabling and disabling Actions, and also handles installing [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks) on the Actions. When multiple Player Input components use the same Actions, the components automatically create [private copies of the Actions](RespondingToActions.md#using-actions-with-multiple-players).
+The Player Input component automatically handles enabling and disabling Actions, and also handles installing [callbacks](RespondingToActions.md#responding-to-actions-using-callbacks) on the Actions. When multiple Player Input components use the same Actions, the components automatically create [private copies of the Actions](RespondingToActions.md#using-actions-with-multiple-players). This is why, when writing input code that works with the PlayerInput component, you should not use `InputSystem.actions` because this references the "singleton" copy of the actions rather than the specific private copy associated with the PlayerInput instance you are coding for.
 
 When first enabled, the Player Input component enables all Actions from the the [`Default Action Map`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_defaultActionMap). If no default Action Map exists, the Player Input component does not enable any Actions. To manually enable Actions, you can call [`Enable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Enable) and [`Disable`](../api/UnityEngine.InputSystem.InputActionMap.html#UnityEngine_InputSystem_InputActionMap_Disable) on the Action Maps or Actions, like you would do [without `PlayerInput`](Actions.md). To check which Action Map is currently enabled, or to switch to a different one, use the  [`PlayerInput.currentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_currentActionMap) property. To switch Action Maps with an Action Map name, you can also call [`PlayerInput.SwitchCurrentActionMap`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_SwitchCurrentActionMap_System_String_).
 

Packages/com.unity.inputsystem/Documentation~/TableOfContents.md

@@ -5,8 +5,8 @@
   * [Concepts](Concepts.md)
   * [Workflows](Workflows.md)
     * [Workflow - Actions](Workflow-Actions.md)
-    * [Workflow - PlayerInput Component](Workflow-PlayerInput.md)
-    * [Workflow - Directly Read Devices](Workflow-Direct.md)
+    * [Workflow - Actions & PlayerInput](Workflow-PlayerInput.md)
+    * [Workflow - Direct](Workflow-Direct.md)
 * [Using the Input System]()
   * [Project-Wide Actions](ProjectWideActions.md)
   * [Configuring Input](ActionsEditor.md)

Packages/com.unity.inputsystem/Documentation~/Workflow-Actions.md

@@ -98,3 +98,11 @@ public class Example : MonoBehaviour
 > **Note:** You should avoid using `FindAction` in your Update() loop, because it performs a string-based lookup which could impact performance. This is why the Action refeferences in the example above are found during the Start() functionm, and stored in variables after finding them.
 
 > **Note:** The [InputSystem.actions](../api/UnityEngine.InputSystem.InputSystem.html) API refers specifically to the Action Asset assigned as the [project-wide actions](ProjectWideActions.md). Most projects only require one Action Asset, but if you are using more than one Action Asset, you must create a reference using the type InputActionAsset to the asset you wish to access.
+
+## Pros and Cons
+
+This is the recommended workflow with the Input System Package, providing a flexible but simple solution suitable for most projects.
+
+You benefit from the Action-based features such as Action Maps, Bindings, and the ability to configure them in the Actions Editor. You can also implement [user rebinding at run time](ActionBindings.html#interactive-rebinding).
+
+This workflow alone doesn't provide built-in support for local multiplayer scenarios with multiple devices, so if you are producing a local multiplayer game you might want to consider using the [Actions & PlayerInput](./Workflow-PlayerInput.md) workflow.

Packages/com.unity.inputsystem/Documentation~/Workflow-Direct.md

@@ -40,7 +40,9 @@ public class MyPlayerScript : MonoBehaviour
 
 The example above reads values directly from  the right trigger, and the left stick, of the currently connected [gamepad](Gamepad.html). It does not use the input system’s "Action" class, and instead the conceptual actions in your game or app, such as "move" and "use", are implicitly defined by what your code does in response to the input. You can use the same approach for other Device types such as the [keyboard](../api/UnityEngine.InputSystem.Keyboard.html) or [mouse](../api/UnityEngine.InputSystem.Mouse.html).
 
-This is often the fastest way to set up some code which responds to input, but it is the least flexible because there is no abstraction between your code and the values generated by a specific device.
+## Pros and Cons
+
+This can be the fastest way to set up some code which responds to input, but it is the least flexible because there is no abstraction between your code and the values generated by a specific device.
 
 If you choose to use this technique:
 

Packages/com.unity.inputsystem/Documentation~/Workflow-PlayerInput.md

@@ -11,7 +11,7 @@ The highest level of abstraction provided by the Input System is when you use [A
 
 It allows you to set up these connections using a UI in the inspector using an event-driven model, instead writing code to poll the values of your Actions as described in the [previous workflow example](Workflow-Actions.html)).
 
-The PlayerInput component also helps with multi-player scenarios. You can use the PlayerInput component along with the PlayerInputManager component to handle automatic instantiation of new players when input occurs on new devices. For example, if you were making a four-player local cooperative game, PlayerInput with PlayerInputManager can handle allowing new players to join when they press start on their respective controller.
+The PlayerInput component also helps with local multi-player scenarios. You can use the PlayerInput component along with the PlayerInputManager component to handle automatic instantiation of new players when input occurs on new devices. For example, if you were making a four-player local cooperative game, PlayerInput with PlayerInputManager can handle allowing new players to join when they press start on their respective controller.
 
 
 ![image alt text](./Images/PlayerInputWithGameplayEvents.png)
@@ -55,9 +55,13 @@ public class ExampleScript : MonoBehaviour
 >
 > This is because the PlayerInput component performs device filtering to automatically assign devices to multiple players, so each instance has its own copy of the actions filtered for each player. If you bypass this by reading `InputSystem.actions` directly, the automatic device assignment won't work.
 
-This workflow has pros and cons when compared to the previous workflow which uses an [Actions without a PlayerInput component](Workflow-Actions.html).
+## Pros and Cons
 
-You can see compared with the previous workflow, this workflow requires less code, because you do not have to reference the Actions Asset or set up the event handler methods in your own script. However it does require more set-up in the Editor, and could make debugging more difficult because the connections between your actions and code are not hard-coded.
+This workflow has pros and cons when compared to using [Actions without a PlayerInput component](Workflow-Actions.html). Because it builds on the use of Actions, it comes with all the benefits provided by them, such as Action Maps, Bindings, and the ability to configure them in the Actions Editor. You can also implement [user rebinding at run time](ActionBindings.html#interactive-rebinding).
+
+This workflow also allows you to set up callbacks in the Editor using an interface in the Inspector, which can sometimes reduce code complexity but can also make debugging more difficult, because the connections between your actions and code are not themselves defined in your code.
+
+It also provides ready-made handling of the [assignment of devices](PlayerInput.html#device-assignments) and [screen-splitting](PlayerInputManager.html#split-screen) in local multiplayer scenarios. While these are things you can implement yourself, having a simple solution ready to go can be beneficial. However if you choose this option, the implementation is somewhat of a "black box", meaning you are less able to customise how it works.
 
 As with the other workflows described in this section, there is a trade-off between flexibility, simplicity, and speed of implementation.
 

Packages/com.unity.inputsystem/Documentation~/Workflows.md

@@ -15,9 +15,9 @@ The descriptions below describe these main workflows and link to more detailed d
 
 |   |   |
 |---|---|
-|[**Configure Actions in the Editor and read their values from Action references in your script**](Workflow-Actions.md)<br/><br/>This is the **recommended** workflow for most situations. In this workflow, you use the Input Settings window to configure your project-wide actions and bindings, then set up references and read the values for those actions in your code [(read more)](Workflow-Actions.md).<br/><br/>|![image alt text](Images/Workflow-Actions.png)|
-|[**Configure input in the Editor, use PlayerInput component to handle events**](Workflow-PlayerInput.html)<br/><br/>This workflow adds more complex functionality on top of the first workflow. It provides features that allow you to connect up **callbacks** directly from Actions to your own callback handler methods, removing the need to deal with Action references in your code. It also provides features that are useful in **local multiplayer** scenarios such as device assignment and split-screen functionality.  [(read more)](Workflow-PlayerInput.html).<br/><br/>|![image alt text](Images/Workflow-PlayerInput.png)|
-|[**Read user input directly from devices**](Workflow-Direct.html)<br/><br/>This workflow is a simplified, script-only approach. It bypasses the Actions and Bindings features entirely, and instead your  script explicitly references specific device controls (such as "left gamepad stick") and reads the values directly. This is suitable for **fast prototyping**, or single fixed platform scenarios. It is a **less flexible** workflow because it bypasses some of the main input system features [(read more)](Workflow-Direct.html). <br/><br/>|![image alt text](Images/Workflow-Direct.png)|
+|[**Using Actions**](Workflow-Actions.md)<br/><br/>This is the **recommended** workflow for most situations. In this workflow, you use the [Actions Editor window](./ActionsEditor.md) to configure sets of actions and bindings, then set up references and read the values for those actions in your code [(read more)](Workflow-Actions.md).<br/><br/>|![image alt text](Images/Workflow-Actions.png)|
+|[**Using Actions and the PlayerInput Component**](Workflow-PlayerInput.html)<br/><br/>This workflow provides extra features that allow you to connect up **callbacks** directly from Actions to your own callback handler methods, removing the need to deal with Action references in your code. It also provides features that are useful in **local multiplayer** scenarios such as device assignment and split-screen functionality.  [(read more)](Workflow-PlayerInput.html).<br/><br/>|![image alt text](Images/Workflow-PlayerInput.png)|
+|[**Directly read device states**](Workflow-Direct.html)<br/><br/>This workflow is a simplified, script-only approach which bypasses the Actions and Bindings features entirely. Instead your script explicitly references specific device controls (such as "left gamepad stick") and reads the values directly. This is suitable for **fast prototyping**, or single fixed platform scenarios. It is a **less flexible** workflow because it bypasses some of the main input system features [(read more)](Workflow-Direct.html). <br/><br/>|![image alt text](Images/Workflow-Direct.png)|