Update documentation

Kobzol · Kobzol · commit 282a5dc1317b · 2021-06-23T16:26:50.000+02:00
diff --git a/docs/arrays.md b/docs/arrays.md
@@ -29,24 +29,27 @@ When a task is started then the following environment variables are created:
 * HQ_TASK_ID - Task id
 
 
-## Tasks states
+## Task states
 
-Each task has its own individual state as defined in the previous chapter.
-The number of tasks with each state can be seen by:
+Each task has its own individual state as defined in the [previous chapter](jobs.md).
+The number of tasks with each state can be displayed by the following command:
 
 ``$ hq job <job_id>``
 
-State of each task can be seen:
+Detailed state of each task will also be included if you pass the `--tasks` flag:
 
 ``$ hq job <job_id> --tasks``
 
-A global job state for summary outputs is derived as following (when a rule is matched, the rest is ignored):
+A global job state for summary outputs is derived from the state of its tasks by the first rule that matches from the
+following list of rules:
 
-* If at least one task is in state "Running" then job state is "Running".
-* If at least one task is in state "Canceled" then job state is "Canceled".
-* If at least one task is in state "Failed" then job state is "Failed".
-* If at least all tasks are in state "Finished" then job state is "Finished".
-* Otherwise the job state is "Waiting".
+
+1. If at least one task is in state "Running", then job state is "Running".
+2. If at least one task has not been computed yet, then job state is "Waiting".
+   A task has been computed once it has reached the `canceled`, `failed` or `finished` state.
+3. If at least one task is in state "Canceled" then job state is "Canceled".
+4. If at least one task is in state "Failed" then job state is "Failed".
+5. All tasks have to be in state "Finished", therefore the job state will also be "Finished".
 
 
 ## Task fail in array job
diff --git a/docs/jobs.md b/docs/jobs.md
@@ -116,18 +116,18 @@ Running-----------------|
 Finished    Failed   Canceled
 ```
 
-* *Submitted* - Only an informative state that a submission was successfull; it is immediately changed into "Waiting" state.
-* *Waiting* - The task is waiting for start
+* *Submitted* - Only an informative state that a submission was successful; it is only shown immediately after a submit.
+* *Waiting* - The task is waiting to be executed.
 * *Running* - The task is running in a worker. It may become "waiting" again when a worker (where the task is running) is lost.
-* *Finished* - The task was sucessfully finished.
-* *Failed* - The task failed. The error can be shown by ``hq job <job-id>``.
-* *Canceled* -  The task was canceled by a user.
+* *Finished* - The task has successfully finished.
+* *Failed* - The task has failed. The error can be shown by ``hq job <job-id>``.
+* *Canceled* -  The task has been canceled by a user.
 
 
 ## Job states
 
-In simple jobs, job state correspondes directly to the state of its a single task. In case of task arrays, see the chapter about task arrays.
-
+In simple jobs, job state corresponds directly to the state of its single task. In the case of task arrays, see the chapter
+about [task arrays](arrays.md).
 
 ## Canceling jobs
 
