Update TechDocs Assessments based on work with Expert Support

[nate-double-u]

Expert Support has been working with CNCF on TechDocs Assessments for:

• in-toto
• Backstage
• etcd

This issue is a discussion about changes we should make to the process (how to, criteria, and template) based on this work.

[dwelsch-esi]

Per Paul G., propose the following changes to the TechDoc assessment program:

• “TechDocs Assessments Program” becomes “TechDocs Assistance Program
• ”The “Assessment” report becomes “Doc Analysis” the first step in the process.
• The “Doc Analysis Report” loses the scoring/rating scale in favor of the scale we previously discussed: “Missing / Needs improvement / Adequate / Good / Excellent”
• The Doc Analysis Report is extended to include a proposed Doc User Role Definitions section, and a proposed Doc Organization Proposal. The proposed User Roles and Doc Organizations are "straw-man" docs, intended as starting points for stakeholder discussions leading to consensus-generated final artifacts.

[psgustafson]

The overall program could now look like this:

CNCF TechDocs Assistance Program Overview Phase 0: Training (if needed) <<-- CNCF is funding free training for project contributors and maintainers on doc essentials Phase 1: Doc analysis <<-- tech writer sorts out general state of docs, identifies user roles, proposes docs organization Phase 2: Issues <<-- tech writers create issues for specific tasks writing assignments and other high priority tasks Phase 3: Implementation <<-- community members tackle issues (tech writer to provide reviews and edit support?) Phase 4: Impact analysis <<-- quarterly(?) review of doc issues opened/closed, and new issues

Thoughts?

[dwelsch-esi]

@psgustafson I like Phases 0 - 2. Phases 3 and 4 seem more aspirational from CNCF's perspective because they're the responsibility of the community. That said, hopefully if the community requested a doc analysis then they'll actively pick up the doc development, but:

• I think the best we can do is offer editorial assistance for phase 3.
• I don't think we can impose a schedule for phase 4, or even prescribe a review process -- suggest one, maybe.

Also, remember that phase 1 requires community stakeholder input to identify user roles and objectives.

@nate-double-u ?

[psgustafson]

@dwelsch-esi - I'd have to agree that 3 and 4 are aspirational. But - hopefully - our efforts result in an ongoing effort by the community to continually improve docs as part of their overall efforts. I too am interested in the @nate-double-u take on this. :)

[nate-double-u]

Reviewing some of the criteria doc, I wonder if we look to remove the term "requirement" in the same way we're looking to remove the word "assessment." Typically we don't require projects to do things. We have opinions about how things could be done, and may even disagree with how something is done, but generally unless it's got to do with trademark, or copyright notices it's not really a requirement -- even then we refer to it as a guideline.

[jbogarthyde]

Perhaps change "requirement" to "recommendation"