Merge pull request #2406 from obsidian-tasks-group/document-statuses-…

…report

docs: Document 'Review and check your Statuses' report

docs-snippets/snippet-statuses-overview.md

@@ -12,6 +12,7 @@
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]
 

docs/Getting Started/Statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Introduction
 
 > [!released]
@@ -22,6 +24,7 @@ Once you're comfortable with the background information in this page, further in
 - [[Style custom statuses|How to style custom statuses]].
 - [[Set up custom statuses|How to set up your custom statuses]].
 - [[About Status Collections]].
+- [[Check your Statuses]].
 
 ## Do I need to set up statuses?
 
@@ -154,6 +157,7 @@ What Tasks' custom statuses allow you to do is to **also customise the behaviour
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]
 

docs/Getting Started/Statuses/About Statuses.md

@@ -4,7 +4,7 @@ publish: true
 
 # About Statuses
 
-<span class="related-pages">#index-pages</span>
+<span class="related-pages">#index-pages #feature/statuses</span>
 
 This section provides more detail to flesh out the introductory material in [[Statuses]].
 
@@ -18,6 +18,7 @@ This section provides more detail to flesh out the introductory material in [[St
 
 - [[Status Settings]]
 - [[Editing a Status]]
+- [[Check your Statuses]]
 
 ## Statuses in Use
 

docs/Getting Started/Statuses/Check your Statuses.md

@@ -0,0 +1,42 @@
+---
+publish: true
+---
+
+# Check your Statuses
+
+<span class="related-pages">#feature/statuses</span>
+
+> [!released]
+> Introduced in Tasks X.Y.Z.
+
+## Overview
+
+At any time you can **validate** and **visualise** your custom statuses, using the **'Review and check your Statuses' button** in Tasks' [[Status Settings]].
+
+## The output file
+
+- A Markdown report is written to the root of the vault.
+- Example file name:
+  - `Tasks Plugin - Review and check your Statuses 2023-11-08 21-30-15`
+- By adding the date and time to the end of the file name, you can create a series of reports, and review the differences.
+- You can of course delete the files at any time.
+
+## Content of the report
+
+The sections are:
+
+- **About this file**
+  - An introduction.
+- **Status Settings**
+  - A table of the statuses in your settings.
+  - Here you can find advice on any potential issues in your status settings.
+- **Loaded Settings**
+  - This has a **Mermaid diagram** showing transitions between your statuses.
+  - View the report in Live Preview or Reading Mode, to see the diagram.
+
+## Example statuses report
+
+Here is an example report, that is generated from the problem statuses shown in [[Recurring Tasks and Custom Statuses#When DONE is not followed by TODO or IN_PROGRESS|When DONE is not followed by TODO or IN_PROGRESS]]:
+
+![Example statuses report](../../images/settings-statuses-report.png)<br>
+*Example statuses report*

docs/Getting Started/Statuses/Core Statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Core Statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Overview
 
 Core statuses represent conventional markdown tasks:
@@ -26,6 +28,9 @@ Note that `Todo` is followed by `Done`, in order to preserve compatibility with
 > [!info]
 You can edit the 'Todo' core status to make its Next Status Symbol be `/` and enable `Todo` -> `In Progress` -> `Done`, if you prefer.
 
+> [!Tip]
+> Use the "Review and check your Statuses" button at any time to [[Check your Statuses]] and to visualise them.
+
 ## Editing core statuses
 
 The only restriction on editing core statuses is that you cannot change their Status Symbols.

docs/Getting Started/Statuses/Custom Statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Custom Statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Introduction
 
 > [!released]
@@ -65,6 +67,7 @@ And this is how you can use them:
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]
 

docs/Getting Started/Statuses/Editing a Status.md

@@ -4,6 +4,8 @@ publish: true
 
 # Editing a Status
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Overview
 
 This page describes features of the modal used for editing a Status.

docs/Getting Started/Statuses/Example Statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Example Statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Overview
 
 Once we know what [[Statuses]] are, what can we do with them?

docs/Getting Started/Statuses/Recurring Tasks and Custom Statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Recurring Tasks and Custom Statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 > [!Note]
 > This page assumes basic familiarity with [[Recurring Tasks]].
 >
@@ -155,6 +157,8 @@ Note that the new task has `CANCELLED` status, so will not typically show up in
 
 > [!Tip]
 > Currently, if you plan to use recurring tasks, you should always ensure that any statuses of type `DONE` are always followed by statuses of type `TODO`.
+>
+> You can [[Check your Statuses]] for any statuses that do not follow this guideline.
 
 > [!Note]
 > When [[Custom Statuses]] were introduced, and we had to figure out how integrate them with recurring tasks, we expected that users would always following `DONE` with `TODO`.

docs/Getting Started/Statuses/Status Settings.md

@@ -4,6 +4,8 @@ publish: true
 
 # Status Settings
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Overview
 
 This is what you see in the Tasks settings when you first look at the Task Statuses section:
@@ -99,3 +101,6 @@ This allows you to try out each of the buttons above, and if you don't like them
   - The mechanism to remember which sections were collapsed is not yet working.
 - Usability wise, it would be good if the 'Add New Task Status' button opened the modal to immediately edit the new status.
 - Ideally, the lists of statuses, with their delete and edit buttons, would be a table instead, with the ability to edit the properties directly in the table, instead of having to open up a modal.
+
+> [!Tip]
+> Use [[Check your Statuses]] to easily find any issues with your Custom Statuses.

docs/Getting Started/Statuses/Status Types.md

@@ -4,6 +4,8 @@ publish: true
 
 # Status Types
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Overview
 
 With the new ability to create a variety of [[Custom Statuses]], Tasks needs to know enough about each status that it can decide:

docs/How To/Set up custom statuses.md

@@ -4,6 +4,8 @@ publish: true
 
 # Set up custom statuses
 
+<span class="related-pages">#feature/statuses</span>
+
 ## Motivation
 
 This page shows you how to customise the statuses used in your Tasks vault, once you have decided which letters and symbols inside `[` and `]` you wish to use, and what they should be called.
@@ -134,6 +136,7 @@ Repeat again:
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]
 

docs/How To/Style custom statuses.md

@@ -4,7 +4,7 @@ publish: true
 
 # Style custom statuses
 
-<span class="related-pages">#css</span>
+<span class="related-pages">#css #feature/statuses</span>
 
 ## Summary
 
@@ -96,6 +96,7 @@ Now the above three tasks look more colourful, and tasks with `[x]` and `[X]` ar
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]
 

docs/Introduction.md

@@ -13,6 +13,7 @@ _In recent [releases](https://github.com/obsidian-tasks-group/obsidian-tasks/rel
     Move the older ones down to the top of the comment block below...
 -->
 
+- X.Y.Z: 🔥 Add 'Review and check your Statuses' facility: see [[Check your Statuses|check your statuses]].
 - X.Y.Z: 🔥 Enable [[Custom Filters|custom filters]] and [[Custom Grouping|custom grouping]] to use [[Query Properties|query properties]] directly - no placeholders required.
 
 <!--

docs/Reference/Status Collections/About Status Collections.md

@@ -6,7 +6,7 @@ aliases:
 
 # About Status Collections
 
-<span class="related-pages">#index-pages</span>
+<span class="related-pages">#index-pages #feature/statuses</span>
 
 ## Background
 
@@ -29,6 +29,7 @@ You can control the behaviour of your tasks (such as what happens when you click
 >   - [[Style custom statuses|How to style custom statuses]].
 > - Configure Tasks to use your custom statuses
 >   - [[Set up custom statuses|How to set up your custom statuses]]
+>   - [[Check your Statuses]]
 > - Optionally, update your tasks searches to take advantage of the new flexibility
 >   - [[Filters#Filters for Task Statuses|Filters for Task Statuses]]