Update doc analysis criteria #286
Conversation
|
Thanks for this @dwelsch-esi, I've removed the |
There was a problem hiding this comment.
Thanks for these updates @dwelsch-esi. See inline for a few initial comments. I'll provide more later, but could you first rebase from main at HEAD, and ensure that all checks are passing?
| named according to user goals?) | ||
| We evaluate on the following: | ||
|
|
||
| - Is there high level conceptual/“About” content? |
There was a problem hiding this comment.
I'd avoid using using "about":
| - Is there high level conceptual/“About” content? | |
| - Is there high level conceptual content? |
| - Is the documentation feature-complete? (i.e., every product feature is | ||
| documented) |
There was a problem hiding this comment.
| - Is the documentation feature-complete? (i.e., every product feature is | |
| documented) | |
| - Is every product feature documented? |
Signed-off-by: Dave Welsch <dwelsch@expertsupport.com>
… CNCF doc analyses. Signed-off-by: Dave Welsch <dwelsch@expertsupport.com>
Signed-off-by: Nate W <natew@cncf.io>
chalin
force-pushed
the
criteria-update-1
branch
from
7461f99 to
3784d9b
Compare
Signed-off-by: Patrice Chalin <pchalin@gmail.com>
| We evaluate on the following: | ||
|
|
||
| - Incubating: Are all [website guidelines][] satisfied? Graduated: Are all | ||
| guidelines satisfied? | ||
| - Incubating: Was a [docs assessment][] requested through CNCF service desk? | ||
| Graduated: All follow-up actions addressed? | ||
| - Incubating: User roles identified and doc needs documented? Graduated: All | ||
| stakeholder need identified? | ||
| - Incubating: Website hosted directly? Graduated: Hosted directly? | ||
| - Incubating: Is the [docs assessment][] comprehensive, addressing most | ||
| stakeholder needs? Graduated: Fully addresses needs of key stakeholders? |
There was a problem hiding this comment.
I prefer the breakdown that we had before. At a minimum, can you organize it in a list, with the first-level list items are maturity levels like we had before?
@nate-double-u WDYT?
| ### Minimal website requirements | ||
|
|
||
| Listed here are the _minimal_ website requirements for projects based on their | ||
| [maturity level][]: sandbox, incubating, graduated and archived. | ||
| [maturity level]: sandbox, incubating, graduated and archived. |
There was a problem hiding this comment.
Keep the trailing [], it helps tools like VS Code know that this is, for sure, a markdown link reference:
| [maturity level]: sandbox, incubating, graduated and archived. | |
| [maturity level][]: sandbox, incubating, graduated and archived. |
| Plan for suitable [accessibility] measures for your website. For example: | ||
|
|
||
| We evaluate on the following: |
There was a problem hiding this comment.
Copy-paste error here? It doesn't make sense to have two phrases ending in colons. Maybe you meant:
| Plan for suitable [accessibility] measures for your website. For example: | |
| We evaluate on the following: | |
| Plan for suitable [accessibility][] measures for your website. For example, we | |
| evaluate on the following: |
| @@ -329,3 +351,4 @@ Example: | |||
|
|
|||
| - Is your website accessible via HTTPS? | |||
| - Does HTTP access, if any, redirect to HTTPS? | |||
| - Are links to external websites or applications working and current? | |||
There was a problem hiding this comment.
Good addition! Actually, we want to know if links (be they internal or external) are valid.
|
Hurray, file format and link checking are passing! We can address the markdown linter issues after the other prose comments have been addressed IMHO. |
Update criteria to include common findings from the last two years of CNCF doc analyses.