Add explanation of dispatch type differences

README.md

@@ -111,9 +111,17 @@ You can use a [PAT](https://help.github.com/en/github/authenticating-to-github/c
 
 By default, the action creates [repository_dispatch](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events.
 Setting `dispatch-type` to `workflow` will instead create [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events.
-
 There are significant differences in the action's behaviour when using `workflow` dispatch. See [workflow dispatch](docs/workflow-dispatch.md) for usage details.
 
+For the majority of use cases, the default `repository` dispatch will likely be the most suitable for new workflows.
+If you already have `workflow_dispatch` workflows, you can execute them with slash commands using this action.
+
+| Repository Dispatch (default) | Workflow Dispatch |
+| --- | --- |
+| Events are created with a `client_payload` giving the target workflow access to a wealth of useful [context properties](https://github.com/peter-evans/slash-command-dispatch/tree/dev#accessing-contexts). | A `client_payload` cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match named arguments supplied with the slash command. |
+| Slash commands can only execute workflows in the target repository's default branch. | Slash commands can execute workflows in any branch using the `ref` named argument. The reference can be a branch, tag, or a commit SHA. |
+| Immediate command validation feedback is unavailable when creating the dispatch event. | Immediate command [validation feedback](https://github.com/peter-evans/slash-command-dispatch/blob/dev/docs/workflow-dispatch.md#validation-errors) is available as an action output. |
+
 ### How comments are parsed for slash commands
 
 Slash commands must be placed in the first line of the comment to be interpreted as a command.

docs/workflow-dispatch.md

@@ -11,7 +11,7 @@ There are significant differences in the action's behaviour when using `workflow
 - When issuing a slash command with arguments, *only named arguments are accepted*. Unnamed arguments will be ignored.
 - A maximum of 10 named arguments are accepted. Additional named arguments after the first 10 will be ignored.
 - `ref` is a reserved named argument that does not count towards the maximum of 10. This is used to specify the target reference of the command. The reference can be a branch, tag, or a commit SHA. If you omit the `ref` argument, the target repository's default branch will be used.
-- A `client_payload` context cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match the named arguments supplied with the slash command.
+- A `client_payload` context cannot be sent with [workflow_dispatch](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) events. The target workflow can only make use of up to 10 pre-defined inputs, the names of which must match named arguments supplied with the slash command.
 
 ## Handling dispatched commands