@hawkeyexl/manni 4.12.4 → 4.13.0

package/templates/lint/tgdp/how-to.yaml

@@ -18,47 +18,61 @@ templates:
   how-to:
     types:
       - how-to
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/how-to/guide_how-to.md
+    description: >-
+      Walk a reader who already knows the product through the steps to
+      complete one task.
     sections:
+      # What the guide explains, and optionally when and why a reader
+      # would want to do it. A how-to that does not say what task it
+      # covers is not a how-to, so at least one paragraph is required.
       - id: overview
         description: >-
-          What the guide explains, and optionally when and why a reader
-          would want to do it. A how-to that does not say what task it
-          covers is not a how-to, so at least one paragraph is required.
+          Say what task this guide covers, and when and why a reader would
+          do it.
         heading: Overview
         max: 1
         contains:
           paragraphs:
             min: 1
+      # Prerequisites. Upstream marks this "{This section is optional}",
+      # and the authoring guide repeats that, so it is not required.
+      # Its shape varies too much to constrain - a lead-in and a bullet
+      # list in the template, but prose or grouped categories in the
+      # guide's own examples - so no content counts are set.
       - id: before-you-start
         description: >-
-          Prerequisites. Upstream marks this "{This section is optional}",
-          and the authoring guide repeats that, so it is not required.
-          Its shape varies too much to constrain - a lead-in and a bullet
-          list in the template, but prose or grouped categories in the
-          guide's own examples - so no content counts are set.
+          List what the reader needs before starting, such as background
+          knowledge, software, access, or other guides to read first.
         heading: Before you start
         min: 0
         max: 1
+      # The steps. Upstream's heading is the placeholder "{Task name}",
+      # so this is a slot; leaving `max` unbounded lets a page carry
+      # several task sections, which the guide explicitly contemplates
+      # ("you may break down the task into multiple logical sub-tasks").
+      # No `lists` floor: a task that delegates its procedure to
+      # sub-tasks legitimately holds no ordered list of its own.
       - id: task
         description: >-
-          The steps. Upstream's heading is the placeholder "{Task name}",
-          so this is a slot; leaving `max` unbounded lets a page carry
-          several task sections, which the guide explicitly contemplates
-          ("you may break down the task into multiple logical sub-tasks").
-          No `lists` floor: a task that delegates its procedure to
-          sub-tasks legitimately holds no ordered list of its own.
+          Name the task, starting with a verb, then give its steps as a
+          numbered list with one action per step.
         sections:
+          # "### {Sub-task}" - another placeholder heading, and upstream
+          # says to "include a sub-task only if the task is big and
+          # complex", so it is optional and may occur more than once.
           - id: sub-task
             description: >-
-              "### {Sub-task}" - another placeholder heading, and upstream
-              says to "include a sub-task only if the task is big and
-              complex", so it is optional and may occur more than once.
+              Break a large task into smaller parts, each with its own
+              numbered steps.
             min: 0
+      # Related reading. Upstream includes it unconditionally and does not
+      # mark it optional the way it marks "Before you start", so it is
+      # required. Its body is a mix of prose and links, so nothing is
+      # counted.
       - id: see-also
         description: >-
-          Related reading. Upstream includes it unconditionally and does not
-          mark it optional the way it marks "Before you start", so it is
-          required. Its body is a mix of prose and links, so nothing is
-          counted.
+          Link to related topics the reader may want next but does not need
+          to finish this task.
         heading: See also
         max: 1

package/templates/lint/tgdp/readme.yaml

@@ -33,37 +33,51 @@ templates:
   readme:
     types:
       - readme
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/readme/guide_readme.md
+    description: >-
+      Introduce the project, say who it is for, and show how to install,
+      use, and contribute to it.
     sections:
+      # `## {Project} logo and badges`. Explicitly optional upstream.
+      # Anchored on the words either side of the placeholder rather than
+      # left as a slot, so it cannot swallow whatever section happens to
+      # come first.
       - id: logo-and-badges
         description: >-
-          `## {Project} logo and badges`. Explicitly optional upstream.
-          Anchored on the words either side of the placeholder rather than
-          left as a slot, so it cannot swallow whatever section happens to
-          come first.
+          Show the project logo, and any badges for status, build health, or
+          other signs that the project is current.
         min: 0
         max: 1
         heading:
           pattern: "\\b[Ll]ogos?\\b|\\b[Bb]adges?\\b"
+      # `## {Project Name}` - the heading is nothing but a placeholder,
+      # so this is a slot. One section, never a run.
       - id: project-name
         description: >-
-          `## {Project Name}` - the heading is nothing but a placeholder,
-          so this is a slot. One section, never a run.
+          Name the project where readers will see it first, with its URL and
+          owners if they help identify it.
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
+      # Explicitly optional upstream. A table of contents that holds no
+      # list is not one, hence the list minimum.
       - id: table-of-contents
         description: >-
-          Explicitly optional upstream. A table of contents that holds no
-          list is not one, hence the list minimum.
+          List the README's sections as links, so readers can find their way
+          around a long README.
         min: 0
         max: 1
         heading: Table of contents
         contains:
           lists:
             min: 1
+      # What the project is and what it lets you do.
       - id: project-description
-        description: What the project is and what it lets you do.
+        description: >-
+          Say what the project does and why a reader should care, before
+          naming the tools it is built with.
         min: 0
         max: 1
         heading: Project description
@@ -72,86 +86,115 @@ templates:
             min: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
+      # The intended audience and their objective.
       - id: who-this-project-is-for
-        description: The intended audience and their objective.
+        description: >-
+          Say who the project is for, and the problems it helps them solve.
         min: 0
         max: 1
         heading: Who this project is for
         contains:
           paragraphs:
             min: 1
+      # Prerequisites. No list minimum: upstream's own troubleshooting
+      # content shows these sections are as often tables, which the
+      # parser does not count as lists.
       - id: project-dependencies
         description: >-
-          Prerequisites. No list minimum: upstream's own troubleshooting
-          content shows these sections are as often tables, which the
-          parser does not count as lists.
+          List what a reader needs before using the project, and link to how
+          to get each item.
         min: 0
         max: 1
         heading: Project dependencies
+      # `## Instructions for using {Project Name}`, anchored on the
+      # literal opening words. Its subsections are the install/configure/
+      # run/troubleshoot procedure, each of which is itself optional and
+      # itself heading-anchored.
       - id: instructions-for-use
         description: >-
-          `## Instructions for using {Project Name}`, anchored on the
-          literal opening words. Its subsections are the install/configure/
-          run/troubleshoot procedure, each of which is itself optional and
-          itself heading-anchored.
+          Give clear, numbered steps for using the project, grouped into
+          installing, configuring, running, and troubleshooting it.
         min: 0
         max: 1
         heading:
           pattern: "^Instructions\\b"
         sections:
+          # `### Install {Project Name}`.
           - id: install
-            description: "`### Install {Project Name}`."
+            description: Give the steps to install or download the project.
             min: 0
             max: 1
             heading:
               pattern: "^Install"
             sections:
               - min: 0
+                description: Add any subsections this section needs here.
+          # `### Configure {Project Name}`.
           - id: configure
-            description: "`### Configure {Project Name}`."
+            description: Give the steps to configure the project.
             min: 0
             max: 1
             heading:
               pattern: "^Configur"
             sections:
               - min: 0
+                description: Add any subsections this section needs here.
+          # `### Run {Project Name}`.
           - id: run
-            description: "`### Run {Project Name}`."
+            description: >-
+              Give the steps to run the project, and link to a quickstart if
+              there is one.
             min: 0
             max: 1
             heading:
               pattern: "^Run(ning)?\\b"
             sections:
               - min: 0
+                description: Add any subsections this section needs here.
+          # `### Troubleshoot {Project Name}`.
           - id: troubleshoot
-            description: "`### Troubleshoot {Project Name}`."
+            description: >-
+              Describe common problems and how to solve them. A table of
+              issues and solutions works well.
             min: 0
             max: 1
             heading:
               pattern: "^Troubleshoot"
             sections:
               - min: 0
+                description: Add any subsections this section needs here.
           - min: 0
+            description: Add any other usage sections here, after the ones above.
+      # How to contribute, or a link to the contributing guide.
       - id: contributing-guidelines
-        description: How to contribute, or a link to the contributing guide.
+        description: >-
+          Say how to contribute, or link to the project's contributing guide.
         min: 0
         max: 1
         heading: Contributing guidelines
         contains:
           paragraphs:
             min: 1
+      # Links to further reading.
       - id: additional-documentation
-        description: Links to further reading.
+        description: >-
+          Link to further documentation, such as the project website and
+          examples, with a short description of each.
         min: 0
         max: 1
         heading: Additional documentation
+      # Support resources.
       - id: how-to-get-help
-        description: Support resources.
+        description: >-
+          Say where readers can get help, such as a mailing list, a chat
+          channel, or an issue tracker.
         min: 0
         max: 1
         heading: How to get help
+      # The licence the project is published under.
       - id: terms-of-use
-        description: The licence the project is published under.
+        description: State the project's license and any other licensing terms.
         min: 0
         max: 1
         heading: Terms of use
@@ -161,3 +204,4 @@ templates:
       # Tolerate a document that carries more than one top-level heading
       # beyond the ones named above.
       - min: 0
+        description: Add any other sections here, after the ones above.

package/templates/lint/tgdp/reference.yaml

@@ -17,59 +17,71 @@ templates:
   reference:
     types:
       - reference
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/reference/guide_reference.md
+    description: >-
+      Describe the parts of the product in a structured form the reader can
+      scan quickly. Keep step-by-step instructions out of it.
 
     sections:
+      # `## {Reference description}` - a placeholder heading, so a slot.
+      # Summarizes what the reference covers and how it relates to the
+      # rest of the doc set. Required: the guide makes this the section
+      # that "concisely summarizes the reference article's content and
+      # purpose".
       - id: reference-description
         description: >-
-          `## {Reference description}` - a placeholder heading, so a slot.
-          Summarizes what the reference covers and how it relates to the
-          rest of the doc set. Required: the guide makes this the section
-          that "concisely summarizes the reference article's content and
-          purpose".
+          Briefly summarize what this reference covers and what the reader
+          can find in it.
         max: 1
 
+      # `## {Table name or other structured entry}` - a placeholder
+      # heading standing for a repeated section, so a slot with an
+      # unbounded `max`. Claims every consecutive section up to
+      # `commands` or `related`. Optional because it and
+      # `reference-description` are both unconstrained placeholders: the
+      # matcher cannot tell "the description" from "the first entry", so
+      # requiring both would
+      # mandate two H2s where the doctype only asks that entries exist.
+      # The node model can name a table directly (proposal 0065), so this
+      # asks for one. Every parser reports tables now, so the rule runs and
+      # upstream's own table satisfies it. Against a format that cannot
+      # report them the rule is pruned and reported as an
+      # `unsupported_content_kind` warning, rather than silently passing or
+      # failing a page for a shape that format cannot show.
       - id: structured-entry
         description: >-
-          `## {Table name or other structured entry}` - a placeholder
-          heading standing for a repeated section, so a slot with an
-          unbounded `max`. Claims every consecutive section up to
-          `commands` or `related`. Optional because it and
-          `reference-description` are both unconstrained placeholders: the
-          matcher cannot tell "the description" from "the first entry", so
-          requiring both would
-          mandate two H2s where the doctype only asks that entries exist.
-          The node model can name a table directly (proposal 0065), so this
-          asks for one. Every parser reports tables now, so the rule runs and
-          upstream's own table satisfies it. Against a format that cannot
-          report them the rule is pruned and reported as an
-          `unsupported_content_kind` warning, rather than silently passing or
-          failing a page for a shape that format cannot show.
+          Present the reference information in a table the reader can scan.
+          Use one section for each table or group of entries.
         min: 0
         contains:
           tables:
             min: 1
 
+      # `## (Optional) Commands`. The guide calls this "this optional
+      # section" outright. The pattern accepts the heading with the
+      # `(Optional)` marker still attached, as upstream ships it, and
+      # with the marker removed, as an author who keeps the section would
+      # write it. A section named anything else - "CLI commands",
+      # "Command reference" - simply falls to the entry slot above.
       - id: commands
         description: >-
-          `## (Optional) Commands`. The guide calls this "this optional
-          section" outright. The pattern accepts the heading with the
-          `(Optional)` marker still attached, as upstream ships it, and
-          with the marker removed, as an author who keeps the section would
-          write it. A section named anything else - "CLI commands",
-          "Command reference" - simply falls to the entry slot above.
+          List the commands, each with a short description and an example,
+          and say which settings are required or optional.
         min: 0
         max: 1
         heading:
           pattern: '^(?:\(Optional\)\s+)?Commands$'
 
+      # Trailing related-reading sections. Reference pages routinely end
+      # with them, the doctype does not enumerate them, and upstream does
+      # not forbid them. Named so the entry slot above stops before them
+      # rather than asking them for a table. No `max`, so a page can end
+      # with both "Notes" and "See also". With a bound of one, the entry
+      # slot would take the first of the two.
       - id: related
         description: >-
-          Trailing related-reading sections. Reference pages routinely end
-          with them, the doctype does not enumerate them, and upstream does
-          not forbid them. Named so the entry slot above stops before them
-          rather than asking them for a table. No `max`, so a page can end
-          with both "Notes" and "See also". With a bound of one, the entry
-          slot would take the first of the two.
+          Link to related pages, or add notes that the entries above do not
+          cover.
         min: 0
         heading:
           - See also
@@ -80,3 +92,4 @@ templates:
       # Anything after those is the author's own, and upstream does not forbid
       # it, so it is not a finding.
       - min: 0
+        description: Add any other sections here, after the ones above.

package/templates/lint/tgdp/release-notes.yaml

@@ -32,77 +32,106 @@ templates:
   release-notes:
     types:
       - release-notes
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/release-notes/guide_release-notes.md
+    # The page itself. Upstream titles it
+    # `Release notes - {Product name} {Release number}`; only the braced
+    # parts are placeholders, so the literal prefix is the one thing this
+    # template insists on. Its body carries the release version, the
+    # release date, and an optional high-level summary.
     description: >-
-      The page itself. Upstream titles it
-      `Release notes - {Product name} {Release number}`; only the braced
-      parts are placeholders, so the literal prefix is the one thing this
-      template insists on. Its body carries the release version, the
-      release date, and an optional high-level summary.
+      Tell readers what changed in one release and why it matters to them.
+      Start the title with Release notes, then the product name and release
+      number.
     heading:
       pattern: '^Release [Nn]otes\b'
     sections:
+      # Functionality this release adds. Omitted by a release that adds none.
       - id: new-features
-        description: Functionality this release adds. Omitted by a release that adds none.
+        description: >-
+          Describe each new feature and how it benefits the reader, most
+          important first.
         heading: New features
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
 
+      # New functionality that does not switch itself on. Separated from
+      # `New features` upstream because these entries are action items
+      # for the reader, not announcements.
       - id: new-features-requiring-configuration-updates
         description: >-
-          New functionality that does not switch itself on. Separated from
-          `New features` upstream because these entries are action items
-          for the reader, not announcements.
+          Describe each new feature the reader must configure before using
+          it, and what they need to change.
         heading: New features requiring configuration updates
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
 
+      # Changes to functionality that already existed - speed, usability,
+      # behaviour.
       - id: improvements
-        description: Changes to functionality that already existed - speed, usability, behaviour.
+        description: >-
+          Describe changes to existing features and how they benefit the
+          reader, most important first.
         heading: Improvements
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
 
+      # Changes to programmatic interfaces, which have a different audience
+      # from the rest of the page.
       - id: api-web-service-updates
-        description: Changes to programmatic interfaces, which have a different audience from the rest of the page.
+        description: Describe changes to the product's APIs and web services.
         heading: API/Web service updates
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.
 
+      # Defects resolved in this release.
       - id: bug-fixes
-        description: Defects resolved in this release.
+        description: >-
+          Describe what each fix changes for the reader, by comparing what
+          the software did before with what it does now.
         heading: Bug fixes
         min: 0
         max: 1
         sections:
+          # Defects that are known and *not* resolved. Upstream nests this
+          # under `Bug fixes` rather than making it a category of its own,
+          # which puts what is still broken next to what was fixed.
           - id: known-issues
             description: >-
-              Defects that are known and *not* resolved. Upstream nests this
-              under `Bug fixes` rather than making it a category of its own,
-              which puts what is still broken next to what was fixed.
+              Describe the problems this release does not fix, with a
+              workaround where one exists.
             heading: Known issues
             min: 0
             max: 1
             sections:
               - min: 0
+                description: Add any subsections this section needs here.
           - min: 0
+            description: Add any other subsections here, after the ones above.
 
+      # Functionality being retired, with the date it stops being
+      # supported and what replaces it. Upstream writes the heading as
+      # `Optional: Deprecation notice`, so the pattern accepts the
+      # published form as well as the one a real page would use.
       - id: deprecation-notice
         description: >-
-          Functionality being retired, with the date it stops being
-          supported and what replaces it. Upstream writes the heading as
-          `Optional: Deprecation notice`, so the pattern accepts the
-          published form as well as the one a real page would use.
+          Name each feature being removed, say when support ends, and say
+          what replaces it and what the reader must do.
         heading:
           pattern: '^(Optional: )?Deprecation notice$'
         min: 0
         max: 1
         sections:
           - min: 0
+            description: Add any subsections this section needs here.

package/templates/lint/tgdp/troubleshooting.yaml

@@ -33,66 +33,80 @@ templates:
   troubleshooting:
     types:
       - troubleshooting
+    guide: https://gitlab.com/tgdp/templates/-/blob/v1.6.0/troubleshooting/guide_troubleshooting.md
+    # The page itself (H1). Upstream titles it
+    # `# Troubleshooting {product name, feature, or task}`, a placeholder,
+    # so the text is left free. What the doctype does ask for is underneath
+    # it: the one- or two-sentence statement of what the guide covers,
+    # which is how a reader decides in seconds whether they are in the
+    # right document.
     description: >-
-      The page itself (H1). Upstream titles it
-      `# Troubleshooting {product name, feature, or task}`, a placeholder,
-      so the text is left free. What the doctype does ask for is underneath
-      it: the one- or two-sentence statement of what the guide covers,
-      which is how a reader decides in seconds whether they are in the
-      right document.
+      Help the reader solve a problem with the product. Open with a sentence
+      or two on what this guide covers, so readers know at once if they are
+      in the right place.
     contains:
       paragraphs:
         min: 1
     sections:
+      # One thing the reader might be seeing - an error message, a
+      # failure, a performance problem. An unbounded `max` claims every
+      # consecutive H2 whose title starts with "Symptom". The number
+      # upstream attaches (`## Symptom 1`) is not required, so
+      # `## Symptom: sync stalls` is equally acceptable.
       - id: symptom
         description: >-
-          One thing the reader might be seeing - an error message, a
-          failure, a performance problem. An unbounded `max` claims every
-          consecutive H2 whose title starts with "Symptom". The number
-          upstream attaches (`## Symptom 1`) is not required, so
-          `## Symptom: sync stalls` is equally acceptable.
+          Describe one sign of the problem the reader might see, such as an
+          error message or a slowdown. Start the heading with Symptom.
         heading:
           pattern: '^[Ss]ymptoms?\b'
         sections:
+          # One cause of the symptom, optionally followed by its solution
+          # or workaround - `### Cause 1 of symptom 1`, then
+          # `### Solution or workaround to cause 1 of symptom 1`. The
+          # solution is optional within the pair because upstream's own
+          # file pairs a second cause with no heading solution at all.
           - id: cause-or-solution
             description: >-
-              One cause of the symptom, optionally followed by its solution
-              or workaround - `### Cause 1 of symptom 1`, then
-              `### Solution or workaround to cause 1 of symptom 1`. The
-              solution is optional within the pair because upstream's own
-              file pairs a second cause with no heading solution at all.
+              Explain one cause of the symptom, followed by its solution or
+              workaround. Repeat the pair for each cause.
             repeat:
+              # At least one is required: a symptom with no cause is not
+              # a troubleshooting entry. Content is left unconstrained,
+              # because the guide recommends bullet points for symptoms
+              # and numbered steps for solutions, so a section here may
+              # legitimately hold no paragraph at all.
               - id: cause
                 description: >-
-                  At least one is required: a symptom with no cause is not
-                  a troubleshooting entry. Content is left unconstrained,
-                  because the guide recommends bullet points for symptoms
-                  and numbered steps for solutions, so a section here may
-                  legitimately hold no paragraph at all.
+                  Explain one thing that causes the symptom. Start the heading
+                  with Cause.
                 heading:
                   pattern: '^[Cc]auses?\b'
                 max: 1
               - id: solution
+                description: >-
+                  Give the numbered steps that fix this cause, or a workaround.
+                  Start the heading with Solution or Workaround.
                 heading:
                   pattern: '^([Ss]olutions?|[Ww]orkarounds?)\b'
                 min: 0
                 max: 1
+          # Further reading for this symptom. Optional, and anchored, so
+          # the repeating pair above stops at it rather than treating it
+          # as one more cause.
           - id: for-more-information
-            description: >-
-              Further reading for this symptom. Optional, and anchored, so
-              the repeating pair above stops at it rather than treating it
-              as one more cause.
+            description: Link to more help with this symptom.
             heading: For more information
             min: 0
             max: 1
+      # Further reading for the guide as a whole. Upstream writes this
+      # heading at H3, inside the last symptom, which reads like a level
+      # slip - its text ("other sources ... with your product, task, or
+      # feature") is about the product, not about one symptom. Rather
+      # than pick a side, the section is allowed, and optional, at both
+      # levels.
       - id: for-more-information
         description: >-
-          Further reading for the guide as a whole. Upstream writes this
-          heading at H3, inside the last symptom, which reads like a level
-          slip - its text ("other sources ... with your product, task, or
-          feature") is about the product, not about one symptom. Rather
-          than pick a side, the section is allowed, and optional, at both
-          levels.
+          Link to other sources of help with the product, task, or feature.
         heading: For more information
         min: 0
         max: 1