docs: improve jobs docs

docs/mdbook/configuration/Hook.md

@@ -11,6 +11,28 @@ Contains settings for the git hook (commands, scripts, skip rules, etc.). You ca
 - [`exclude_tags`](./exclude_tags.md)
 - [`skip`](./skip.md)
 - [`only`](./only.md)
+- [`jobs`](./jobs.md)
+  - [`name`](./name.md)
+  - [`run`](./run.md)
+  - [`script`](./script.md)
+  - [`runner`](./runner.md)
+  - [`group`](./group.md)
+    - [`parallel`](./parallel.md)
+    - [`piped`](./piped.md)
+    - [`jobs`](./jobs.md)
+  - [`skip`](./skip.md)
+  - [`only`](./only.md)
+  - [`tags`](./tags.md)
+  - [`glob`](./glob.md)
+  - [`files`](./files.md)
+  - [`file_types`](./file_types.md)
+  - [`env`](./env.md)
+  - [`root`](./root.md)
+  - [`exclude`](./exclude.md)
+  - [`fail_text`](./fail_text.md)
+  - [`stage_fixed`](./stage_fixed.md)
+  - [`interactive`](./interactive.md)
+  - [`use_stdin`](./use_stdin.md)
 - [`commands`](./Commands.md)
   - [`run`](./run.md)
   - [`skip`](./skip.md)

docs/mdbook/configuration/group.md

@@ -1,10 +1,10 @@
 ## `group`
 
-Specifies a group of jobs and option to run them with.
+You can define a group of jobs and configure how they should execute using the following options:
 
-- [`parallel`](./parallel.md)
-- [`piped`](./piped.md)
-- [`jobs`](./jobs.md)
+- [`parallel`](./parallel.md): Executes all jobs in the group simultaneously.
+- [`piped`](./piped.md): Executes jobs sequentially, passing output between them.
+- [`jobs`](./jobs.md): Specifies the jobs within the group.
 
 ### Example
 
@@ -16,7 +16,9 @@ pre-commit:
     - group:
         parallel: true
         jobs:
-          - run: echo hello from a group
+          - run: echo 1
+          - run: echo 2
+          - run: echo 3
 ```
 
 > **Note:** To make a group mergeable with settings defined in local config or extends you have to specify the name of the job group belongs to:
@@ -26,5 +28,8 @@ pre-commit:
 >     - name: a name of a group
 >       group:
 >         jobs:
->           - run: echo from a group job
+>           - name: lint
+>             run: yarn lint
+>           - name: test
+>             run: yarn test
 > ```

docs/mdbook/configuration/jobs.md

@@ -1,6 +1,10 @@
 ## `jobs`
 
-Job can either be a command or a script. Configuring `jobs` is more flexible than configuring `commands` and `scripts`, although all options are supported now.
+Jobs provide a flexible way to define tasks, supporting both commands and scripts. Jobs can be grouped which provides advanced flow control.
+
+### Basic example
+
+Define jobs in your `lefthook.yml` file under a specific hook like `pre-commit`:
 
 ```yml
 # lefthook.yml
@@ -11,13 +15,22 @@ pre-commit:
     - run: yarn test
 ```
 
-This is how jobs configuration differ from commands and scripts:
+### Differences from Commands and Scripts
+
+**Optional Job Names**
+
+- Named jobs are merged across [`extends`](./extends.md) and local config.
+- Unnamed jobs are appended in the order of their definition.
 
-- Jobs have optional names. Lefthook merges named jobs across [extends](./extends.md) and [local configs](../examples/lefthook-local.md). Unnamed jobs get appended in the definition order.
-- Jobs can have groups of other jobs. For groups you can specify [`parallel`](./parallel.md) or [`piped`](./piped.md) flow for a bunch of jobs. Also [`glob`](./glob.md) and [`root`](./root.md) parameters of a group apply to all its jobs (even nested).
+**Job Groups**
+
+- Groups can include other jobs.
+- Flow within groups can be parallel or piped. Options like `glob` and `root` apply to all jobs in the group, including nested ones.
 
 ### Job options
 
+Below are the available options for configuring jobs.
+
 - [`name`](./name.md)
 - [`run`](./run.md)
 - [`script`](./script.md)
@@ -42,9 +55,9 @@ This is how jobs configuration differ from commands and scripts:
 
 ### Example
 
-> **Note:** Currently only `root` and `glob` options are applied to group jobs. Other options must be set for each job separately. If you find this inconvenient, please submit a [feature request](https://github.com/evilmartians/lefthook/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.md).
+> **Note:** Currently, only root and glob options are applied to group jobs. Other options must be set for each job individually. Submit a [feature request](https://github.com/evilmartians/lefthook/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.md) if this limits your workflow.
 
-A simple configuration with one piped group which executes in parallel with other jobs.
+A configuration demonstrating a piped group running in parallel with other jobs:
 
 ```yml
 # lefthook.yml
@@ -70,3 +83,5 @@ pre-commit:
     - script: verify.sh
       runner: bash
 ```
+
+This configuration runs migrate jobs in a piped flow while other jobs execute in parallel.