chore: update pull request template, add code review checklist

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,21 +1,30 @@
-> Read our [Contribution guide](https://github.com/eclipse/che-docs/blob/master/CONTRIBUTING.adoc) before submitting a PR.
 
-### What does this PR do?
+<!-- 
+Please use one of the following prefixes for the title:
+docs: Documentation not including procedures. Engineering review is mandatory.
+procedures: Documentation including procedures. Testing procedures is mandatory. Engineering and QE review is mandatory (Engineering can review on behalf of QE). 
+chore: Routine, release, tooling, version upgrades.
+fix: Fix build, language, links, or metadata.
+-->
 
+<!-- Read our [Contribution guide](https://github.com/eclipse/che-docs/blob/master/CONTRIBUTING.adoc) before submitting a PR. -->
 
-### What issues does this PR fix or reference?
+## What does this pull request change?
 
+## What issues does this pull request fix or reference?
 
-### Specify the version of the product this PR applies to.
+## Specify the version of the product this pull request applies to
 
+## Pull Request checklist
 
-### PR Checklist
+The author and the reviewers validate the content of this pull request with the following checklist, in addition to the [automated tests](code_review_checklist.adoc).
 
-As the author of this Pull Request I made sure that:
-
-- [ ] `vale` has been run successfully against the PR branch
-- [ ] Link checker has been run successfully against the PR branch
-- [ ] Documentation describes a scenario that is already covered by QE tests, otherwise an issue has been created and acknowledged by Che QE team
-- [ ] Changed article references are updated where they are used (or a redirect has been configured on the docs side):
-    - [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/src/services/bootstrap/branding.constant.ts)
+- Any procedure:
+  - [ ] Successfully tested.
+- Any page or link rename:
+  - [ ] The page contains a redirection for the previous URL.
+  - Propagate the URL change in:
+    - [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/packages/dashboard-frontend/src/services/bootstrap/branding.constant.ts)
     - [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts)
+- [ ] Builds on [Eclipse Che hosted by Red Hat](https://workspaces.openshift.com).
+- [ ] the *`Validate language on files added or modified`* step reports no vale warnings.

.vale.ini

@@ -57,8 +57,13 @@ properties = md
 BasedOnStyles = CheDocs,IBM,Vale
 # Ignore code surrounded by backticks or plus sign, parameters defaults, URLs.
 TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)
+IBM.Annotations = suggestion
 IBM.HeadingPunctuation = NO
 IBM.Headings = NO
+IBM.Slash = warning
+IBM.Usage = suggestion
+Vale.Repetition = NO
+Vale.Spelling = YES
 
 [*.ini]
 BasedOnStyles = CheDocs,IBM,Vale

.vale/styles/Vocab/Che/accept.txt

@@ -6,6 +6,8 @@
 [Cc]lassloading
 [Cc]he
 [Dd]evfile|[Dd]evfiles
+[Dd]ownstream
+[Dd]ownstreaming
 [Ff]actories|[Ff]actory
 [Gg]it
 [Gg]rafana
@@ -22,6 +24,7 @@
 [Mm]inikube
 [Mm]inishift
 [Mm]ixin|[Mm]ixins
+[Mm]odularization
 [Mm]ulticluster
 [Mm]ultihost
 [Mm]ultinode

CONTRIBUTING.adoc

@@ -96,7 +96,7 @@ TIP: For Antora, a link:https://docs.antora.org/antora/2.3/module-directories/#m
 
 . To review the pull request:
 
-.. Validate the accuracy of content, as well as build, language, links and modular docs requirements.
+.. See the xref:code_review_checklist.adoc[code review checklist].
 
 .. For documentation updates containing testable steps, the documentation pull request needs to have the `team/che-qe` label set and get reviewed by both the documentation team and the Che QA team.
 

code_review_checklist.adoc

@@ -0,0 +1,44 @@
+# Pull request review checklist for committers and reviewers
+:toc: auto
+
+The reviewer validates the content of a pull request with this checklist.
+
+## Automated validation steps
+
+These automated steps block the pull request merge.
+
+* [ ] *`Build and validate PR / link checker (pull_request)`* is successful
+** [ ] *`Build using Antora`* step is successful: documentation is building without warnings, and all AsciiDoc attributes have a definition.
+** [ ] *`Validate links using htmltest`* step is successful: internal and external links are valid.
+** [ ] *`Validate language on files added or modified`* step is successful and reports no vale errors: basic language validation, no major deviations from link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide], and project specific language rules.
+* [ ] *`eclipsefdn/eca`*  is successful: all contributors have signed the Eclipse Contributor Agreement (ECA).
+
+## Non automated validation steps
+
+The author and the reviewers validate the content of a pull request with this additional checklist:
+
+* Any procedure:
+** [ ] Successfully tested.
+* Any page or link rename:
+** [ ] The page contains a redirection for the previous URL.
+** Propagate the URL change in:
+*** [ ] Dashboard [default branding data](https://github.com/eclipse-che/che-dashboard/blob/main/src/services/bootstrap/branding.constant.ts)
+*** [ ] Chectl [constants.ts](https://github.com/che-incubator/chectl/blob/master/src/constants.ts)
+* [ ] Builds on https://workspaces.openshift.com[Eclipse Che hosted by Red Hat].
+* [ ] *`Validate language on files added or modified`* step reports no vale warnings.
+
+## In depth language review checklist
+
+The technical writer reviewers validate the language with this additional in depth checklist. We do recognize the subjectivity of some of these objectives.
+
+- [ ] Content is appropriate for the intended audience.
+- [ ] Downstream friendly: correct use of attributes, `ifdef` statements, examples.
+- [ ] Effective titles.
+- [ ] Follows modularization guidelines. See: link:https://redhat-documentation.github.io/modular-docs/[Modular Documentation Reference Guide].
+- [ ] Follows the principles of minimalism. See: link:https://docs.google.com/presentation/d/1Yeql9FrRBgKU-QlRU-nblPJ9pfZKgoKcU8SW6SQ_UqI/edit#slide=id.g1f4790d380_2_257[The Wisdom of Crowds slides], link:https://youtu.be/s3Em8QSXyn8[The Wisdom of Crowds video], link:https://www.nngroup.com/articles/chunking/[Chunking].
+- [ ] Information is clear, valuable, and concise, no ambiguity.
+- [ ] Language is consistent with the rest of the docs.
+- [ ] Language is compliant with link:https://www.oreilly.com/library/view/the-ibm-style/9780132118989/[IBM Style Guide] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Supplementary Style Guide] rules not implemented in vale.
+- [ ] The information flow is logical.
+- [ ] Uses screenshot and other visuals when required.
+- [ ] Uses verification steps when necessary.