Do we have a Modular Documentation checklist?

[bredamc]

The Modular documentation reference guide and associated templates are very useful when learning about mod docs, thank you!

Do we also have a Modular Documentation checklist? Such a document would be very useful for those who are new to mod docs, and for peer reviews by reviewers who are not familiar with all of the mod doc rules.

[rolfedh]

Hi, @rohennes.

• To what extent are the Asciidoc styles in Vale based on the Mod Docs standard?
• Could it be said that they serve as an automated checklist of the standard's more important features?

[rolfedh]

Hi @bredamc, I raised this issue in today's Modular Documentation Steering Committee meeting and got support for it from @emmurphy1 and @mjahoda.

[bredamc]

@rolfedh That's great, many thanks for raising the issue and letting me know the result!

[aireilly]

The AsciiDoc Vale rules are an attempt to highlight potential issues with AsciiDoc syntax that can cause problems in output, unclosed tables, incorrect ifdefs, etc. You could consider it like an imperfect and (very) limited AsciiDoc Parser. Note that a lot of these validations are done by default with the asciidoctor.js validation in the VS Code plugin.

The OpenShiftAsciiDoc are probably closer to what a Mod Docs rule set would look like. These are project-specific AsciiDoc usage guidelines.

[aireilly]

Click into the rules above to see a one-liner describing what the rule catches.

[rohennes]

Hey Rolfe, +1 to Aidan's comments. AsciiDoc rules are aimed at basic syntax validation. It is a vanilla rule set that can be used inside/outside of Red Hat, so isn't based on any Red Hat specific guidelines like the mod docs guidelines. For more custom metadata, we created the OpenShiftAsciiDoc rules. I don't think you could see them as a checklist for mod docs, although they are complimentary.

A vale rule set for mod docs might be possible, but probably fairly limited. You could have a rule for the following:

• ensure titles use {context} (in modules only)
• no modules in modules
• no subheadings in procedure modules
• text snippet restrictions, such as no IDs or H1 headings

It may be more effort than it's worth though. You'd also need to configure you .vale.ini to ensure module or assembly specific mod-docs rules applied only to assemblies/modules. Bit of a headache...

[jhradilek]

A few years ago, I started a Vale style for exactly this which I recently decided to revive. I do not think it is mature enough and some of the changes I have implemented locally are maybe not suitable for all projects, but I currently have the following functionality:

• Verify that all section IDs include the {context} attribute
• Verify that if the file includes other modules, it assigns the {context} attribute a new value
• Verify that includes that define leveloffset do not add more than one level (not suitable for projects that do not follow the tree-like content structure)
• Verify that procedure modules do not include other modules

Unpushed I also have experimental version of rules that:

• Verify that commands entered at a shell prompt are highlighted in bold (not suitable for all projects and being actively discussed in the Supplementary Style Guide project)
• Verify that code blocks that utilize markup like underscores and asterisks do have subs="quotes" enabled
• Complain when 50% or more of the module contents are comments

[rolfedh]

Wow! This is a great start, @jhradilek.

If you're interested, the newdoc tool that @msuchane created for generating new mod doc files has a deprecated -validate option. I wonder if he has some insights to that might be useful to your project.

For background:

[rdlugyhe@rdlugyhe-thinkpadt14sgen2i rhbq-quarkus]$ newdoc --help
Generate pre-populated module files formatted with AsciiDoc that are used in Red Hat and Fedora
documentation.

Usage: newdoc -a TITLE... -c TITLE... -p TITLE... -r TITLE... -s TITLE... [-i TITLE] -l FILE... [-M]
[-E] [-P] [-A] [-T DIRECTORY] [-v | -q]

Available options:
  Generate or validate files:
    -a, --assembly <TITLE>  Create an assembly file
    -c, --concept <TITLE>  Create a concept module
    -p, --procedure <TITLE>  Create a procedure module
    -r, --reference <TITLE>  Create a reference module
    -s, --snippet <TITLE>  Create a snippet file
    -i, --include-in <TITLE>  Create an assembly that includes the other specified modules
    -l, --validate <FILE>  DEPRECATED: Validate (lint) an existing module or assembly file
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
  Common options:
    -M, --comments     Generate the file with explanatory comments
    -E, --no-examples  Generate the file without any example, placeholder content
    -P, --no-file-prefixes  Do not use module type prefixes (such  -l, --validate <FILE>  DEPRECATED: Validate (lint) an existing module or assembly fileas `proc_`) in file names
    -A, --anchor-prefixes  Add use module type prefixes (such as `proc_`) in AsciiDoc anchors
    -T, --target-dir <DIRECTORY>  Save the generated files in this directory
    -v, --verbose      Display additional, debug messages
    -q, --quiet        Hide info-level messages. Display only warnings and errors
    -h, --help         Prints help information
    -V, --version      Prints version information

[rolfedh]

In #211 (comment), which is very much WIP, @mjahoda proposes having an abbreviated checklist in addition to the comprehensive one.

For simplicity and ease of maintenance, I propose having a single checklist with two parts:

• Part one: Key items
• Part two: All items

The checklist and tooling completement each other:

• The checklists will guide writers writing content.
• The tooling will validate the content and catch issues.

We'll work to ensure that the mod docs standard, checklist, and tooling all align with one another.

[rolfedh]

@jhradilek, I created an issue for the Mod Docs community to discuss the Vale Style for Mod Docs: #212

[msuchane]

If you're interested, the newdoc tool that @msuchane created for generating new mod doc files has a deprecated -validate option. I wonder if he has some insights to that might be useful to your project.

The validation feature in newdoc only ever tested Pantheon 2 and Jupiter requirements. Now that we're moving to a different publishing platform, the tests are obsolete, so I'm removing them. There was very little in the newdoc validation suite that could check the modularity: maybe a test if modules include other modules.

[emmurphy1]

@rolfedh the checklist is a great start. I believe the original request was for a checklist that writers can use when reviewing modularized content. The discussion around vale is really great as well, and it possible it would be fantastic to get check in there. However, I think these are two separate projects. I made a few comments in the MR. In general, I think we need to make the checks more specific.