Address feedback on lifetime of documents

Add clarifications in different sections to address the feedback provided.

Signed-off-by: Walter Lozano <walter.lozano@collabora.com>

content/concepts/document_lifetime.md

@@ -86,11 +86,12 @@ Releases            | -                     | Not meant to have an end of life
 
 # Metadata
 
-Based on the concepts and categories already described the following process
-aims to reduce the gap in-between current status and what the documentation reflects.
+Based on the concepts and categories already described a process needs to be
+created to reduce the gap in-between current status and what the documentation
+reflects.
 
-Documents should include metadata which will make it easier to determine the
-moment an update or review is required.
+To make this possible, documents should include metadata which will make it
+easier to determine the moment an update or review is required.
 
 ## Dates
 
@@ -105,7 +106,7 @@ of review it will require. Most probably, older documents should require a
 deeper review than a newer one.
 
 - `lastmod`, date which advertises when the document was last updated
-with not trivial changes. This modification implies that the document is still
+with non-trivial changes. This modification implies that the document is still
 valid as the committer needed to check the information on it. However this does
 not imply that all the information on it is valid. This date is important as
 some documents could be updated with minor changes, like URL updates, which does
@@ -140,7 +141,8 @@ Some fields can be used to advertise the status of a document, allowing readers
 to quickly spot important information about a document:
 
 - `status`, a string which gives a clear idea of the validity of a document,
-suggested values are "Requires Update", "Deprecated"
+suggested values are "" "Requires Review" "Requires Update", "Deprecated". A
+value of "" or empty indicates that the document is valid.
 
 - `statusDescription`, a short sentence giving additional information about the
 status
@@ -163,7 +165,7 @@ sometimes it results in a long list of documents where the keyword appears but
 it is only referenced, giving it little value.
 
 Tags are useful as they can efficiently connect documents and ideas, but to 
-make this true the should follow these guidelines:
+make this true they should follow these guidelines:
 
 - Tags should be meaningful, the name should condense an important concept leading
 to significant search results. For instance a tag like `Apertis` will have little
@@ -177,10 +179,15 @@ be checked against a list of valid tags.
 order to highlight the relevant information. Initially tags can appear at the
 top of the page to summarize the topics the document covers. Once the tagging
 process is complete, additional pages to list all the available tags can be
-added to improve the user experience.
+added to improve the user experience, by creating a link to
+https://www.apertis.org/tags. However, this should be done only when all the
+documents have a valid tag to avoid showing misleading results.
 
 - Order tagged documents. When searching using tags it will be useful to have
-the list ordered by relevance.
+the list ordered by relevance if the number of matches is higher that 5, to
+highlight the most important documents. This is true only when searching for
+tags, other searching and listing should follow the current approach of sorting
+by title.
 
 As an example this is a list of proposed tags, the list is not meant to be
 exhaustive:
@@ -211,9 +218,11 @@ When a new document needs to be created to help users of Apertis take full
 advantage of it, a set of steps should be followed to ensure that it will be
 supported over time:
 
-- Choose the type of document as described in {{ #document-types }}
+- Choose the type of document as described in [document types]( #document-types )
 - Choose a title which describes the document
-- Add creation date metadata
+- Add `date` metadata as creation date
+- Add `lastmod` metadata as a placeholder with empty value
+- Add `lastreview` metadata as a placeholder with empty value
 - Add tags to link the document to other (when tags are widely available) documents
 - Use neutral language, focus on simplicity, since many Apertis users are not
 native English speakers
@@ -260,7 +269,10 @@ such as historical reason, this fact should be reflected with the `status` and
 
 The main purpose of documentation is to be consumed by users. In this regard,
 having feedback on different aspects of its usage is a key element to design
-a documentation strategy.
+a documentation strategy. Feedback can be collected from different sources, such
+as analyzing visits or performing simple pools. The results of these feedback
+should be summarized in a web interface in order to provide information to help
+improve documentation.
 
 ## Changes and contributors
 
@@ -296,7 +308,7 @@ such as
 [GDPR](https://ec.europa.eu/info/law/law-topic/data-protection_en)
 to ensure personal data protection.
 
-## Results
+## Dashboard
 
 The information generated based on the previous comments should be available
 through a web page with administrator restrictions, to have a single point to
@@ -316,14 +328,17 @@ The result obtained from statistics should provide the basis to infer:
 - Topics where documentation is more consumed
 - Possible reviewers
 
+The recommendation is to include these reports in a `dashboard`
+similar to current [package dashboard](https://infrastructure.pages.apertis.org/dashboard/)
+
 # Automated tasks
 
 Keeping documentation reliable is impossible without setting an automated task.
 There are two kinds of automated tasks that can help to address potential issues
 which can be implemented with CI pipelines.
 
-- Pipeline for branches: on every branch change, several checks should be
-performed to ensure the health of documentation:
+- Pipeline for work in progress branches: on every branch change, several
+checks should be performed to ensure the health of documentation:
   - Documents updated should provide `title` and `date`
   - Documents updated with non-trivial changes should have a valid
   `lastmod`, in a time window of one month. Since it is not
@@ -336,13 +351,21 @@ performed to ensure the health of documentation:
   - Ensure formatting follows a standard 
   - Test code blocks for syntax errors
 
+  Any issue with the performed checks should make the pipeline fail preventing
+  a merge requests to be merged and reported in the pipeline log to help
+  submitter to fix it.
+
 - Scheduled pipeline: a pipeline should be triggered on a weekly basis to ensure:
-  - Documents provide valid external links
-  - Documents which require a review are tagged as "Review required"
+  - Documents provide valid external links. A task should be automatically
+  created to address any update requirement
+  - Documents which have reached their lifetime period since the `lastreview`
+  are highlighted. A task should be automatically created to change the
+  `status` to "Requires review" for all the documents in this situation. A
+  separated task should be created to review each of these documents
   - A task is created to ensure documents that have reached their lifetime
   period since the `lastreview` will be reviewed
-  - A task is created to ensure links are valid
-  - Update statistics reports based on:
+  - Update statistics reports available trough the [dashboard](#dashboard)
+    based on:
     - Changes and contributors
     - Visits
     - Surveys