Analysis templates suggested updates#357
Conversation
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
✅ Deploy Preview for cncf-techdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
| users needing more help? (FAQ, Troubleshooting) | ||
| - If the product exposes an API, is there a complete reference? | ||
| - Is content up to date and accurate? | ||
|
|
There was a problem hiding this comment.
Consider adding for information architecture:
- Are prerequisites consistent in quickstarts and install topics? Consider consolidating if applicable.
- Are there instructions on how to install something that is better served by linking to official documentation?
- Is there content in other places that would be helpful for getting started content.
There was a problem hiding this comment.
Keep in mind that these criteria are meant to embody best practices for the most important aspects of the documentation. If you're using words like "Consider ...", "better served", and "helpful", you might be describing nice-to-haves. The goal with these criteria is to
Bullet #1 brings up a whole can of worms around document reuse. Prerequisites to procedures vary in length. At one end of the spectrum, if something is boilerplate-y enough that it can be referred to from several procedures, to my mind it's more of a sub-procedure that can be referred to in a single step. At the other end of the spectrum, short prereqs might be worth including in-line even if they're duplicated because you don't want to send users pinballing around the doc to get one task done. You can also write something once and #include it where applicable, but not all site generators support this. The upshot is that IMO this is a judgement that the maintainers have to make on a per-project basis.
Bullet #2 is a good point. I've seen a lot of OSS pages that are duplicates of how to do something with a component tool (especially Kubernetes configuration) that could have been replaced with a short explanation and a link to the component's documentation. On the other hand, too much documentation is better than no documentation. I'd say something like "If your product builds on or incorporates another product (such as Kubernetes), does it provide external references where needed to install and configure those products?"
Not sure what you're getting at in Bullet #3. Please explain further.
There was a problem hiding this comment.
Points well taken, for bullet 1 - indeed repeated procedures and info isn't inherently bad. I'm lately more thinking of "roadmap" guidance for all scenarios (bare metal, via VMs, cloud) in the overview of Getting Started perhaps.
Bullet 3 was in regard finding helpful definitions and context buried in other sections that would be helpful in getting started content. But you can only find these by happenstance or AI now.
|
|
||
| Replace link placeholders in brackets, such as [_PROJECT_][project-website], | ||
| with the actual link surrounded by parenthesis. | ||
|
|
There was a problem hiding this comment.
I added this. Remove if you think its not needed.
| [Inclusive Naming Initiative](https://inclusivenaming.org) website? | ||
| - Does the project use language like "simple", "easy", etc.? | ||
|
|
||
| ### AI Optimization and Discoverability |
There was a problem hiding this comment.
New section. Please opine.
UPDATE: Nate and I discussed this and agreed it would be better in a separate topic. @nate-double-u - how about naming it ai-guidance.md?
There was a problem hiding this comment.
The currently popular description seems to be "AI friendly." I like "optimization and discovery" better -- it's more precise -- but I'd put "AI friendly" in the description somewhere for searchability.
What's the rationale for having a separate document?
There was a problem hiding this comment.
I guess because the topic of AI here is multi-faceted and could be distracting. There's the AI tools for analysis and the AI configurations of optimization and discovery. Probably others.
|
|
||
| #### Project governance documentation | ||
|
|
||
| ## Website and infrastructure |
There was a problem hiding this comment.
We can consider removing Website and infrastructure as writers only have minimal info or context to complete, and Nate has ok'd not including it.
There was a problem hiding this comment.
I think this is situational. In some cases the website and infrastructure review is warranted, in other cases I'm OK dropping it.
There was a problem hiding this comment.
I agree with Nate. There are going to be AI-related components as well, such as an AGENTS.md file.
There was a problem hiding this comment.
Yep, keep it as Claude in the GitHub Copilot CLI can answer some of the website infrastructure criteria questions for us!
dwelsch-esi
left a comment
dwelsch-esi
left a comment
There was a problem hiding this comment.
Since we're taking this opportunity to review and improve the analysis criteria, a couple of overall comments:
-
The analysis process evaluates against the maturity level (or the proposed maturity level) of the project. We don't explicitly map criteria requirements to maturity level, except briefly for website guidelines. Should we consider revising the criteria document to explictly map leveled criteria to the incubating and graduated levels?
-
The doc criteria don't include any process requirements. I understand that each project has its own processes, procedures, and culture. (Some process is alluded to, for example with requirements like "Who reviews and approves documentation pull requests?") On the other hand, process is really what a maturity model is about. Should we start thinking about including doc process in the criteria, especially for a graduated project? These would necessarily have to be general principles, adaptable to a range of OSS projects and their methodologies. For example, we ask if the documentation has versions and release notes, but not if the project has a versioning process.
A maintenance question for the CNCF TechDocs analysis docments: We duplicate the criteria in the analysis template. This makes the template easy to use but risks getting the template out of sync with the criteria. Is there a better way to do this?
| stored; this might be its own repo or a directory in the project main repo | ||
|
|
||
| Replace link placeholders in brackets, such as [_PROJECT_][project-website], | ||
| with the actual link surrounded by parenthesis. |
There was a problem hiding this comment.
| with the actual link surrounded by parenthesis. | |
| with a Markdown-style link. |
| users needing more help? (FAQ, Troubleshooting) | ||
| - If the product exposes an API, is there a complete reference? | ||
| - Is content up to date and accurate? | ||
|
|
There was a problem hiding this comment.
Keep in mind that these criteria are meant to embody best practices for the most important aspects of the documentation. If you're using words like "Consider ...", "better served", and "helpful", you might be describing nice-to-haves. The goal with these criteria is to
Bullet #1 brings up a whole can of worms around document reuse. Prerequisites to procedures vary in length. At one end of the spectrum, if something is boilerplate-y enough that it can be referred to from several procedures, to my mind it's more of a sub-procedure that can be referred to in a single step. At the other end of the spectrum, short prereqs might be worth including in-line even if they're duplicated because you don't want to send users pinballing around the doc to get one task done. You can also write something once and #include it where applicable, but not all site generators support this. The upshot is that IMO this is a judgement that the maintainers have to make on a per-project basis.
Bullet #2 is a good point. I've seen a lot of OSS pages that are duplicates of how to do something with a component tool (especially Kubernetes configuration) that could have been replaced with a short explanation and a link to the component's documentation. On the other hand, too much documentation is better than no documentation. I'd say something like "If your product builds on or incorporates another product (such as Kubernetes), does it provide external references where needed to install and configure those products?"
Not sure what you're getting at in Bullet #3. Please explain further.
|
|
||
| #### Project governance documentation | ||
|
|
||
| ## Website and infrastructure |
There was a problem hiding this comment.
I agree with Nate. There are going to be AI-related components as well, such as an AGENTS.md file.
| [Inclusive Naming Initiative](https://inclusivenaming.org) website? | ||
| - Does the project use language like "simple", "easy", etc.? | ||
|
|
||
| ### AI Optimization and Discoverability |
There was a problem hiding this comment.
The currently popular description seems to be "AI friendly." I like "optimization and discovery" better -- it's more precise -- but I'd put "AI friendly" in the description somewhere for searchability.
What's the rationale for having a separate document?
| contributors to the _PROJECT_ OSS project | ||
| - **Website:** concerns the mechanics of publishing the documentation, and | ||
| includes branding, website structure, and maintainability | ||
|
|
There was a problem hiding this comment.
| A fourth area of concern, AI optimization and discovery, might be included in this analysis. If so, it is discussed in a separate document, `ai-guidance.md`. |
There was a problem hiding this comment.
Dupe.
There was a problem hiding this comment.
| - Are all vital website features usable using a keyboard only? |
There was a problem hiding this comment.
| - Does text-to-speech offer listeners a usable experience? |
|
|
||
| [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility | ||
|
|
||
| ### Branding |
There was a problem hiding this comment.
This isn't my area, but are all the branding criteria still relevant and important? Are there others that should be added?
|
|
||
| We evaluate on the following: | ||
|
|
||
| - Analytics: |
There was a problem hiding this comment.
Are there any AI-era SEO or findability criteria we should add?
Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>
|
|
||
| ### Purpose | ||
|
|
||
| This document was written to analyze the current state of _PROJECT_ |
There was a problem hiding this comment.
It's difficult for a writer to get going on the analysis unless they have all three docs in a PR. Perhaps the last two sentences in this paragraph could be commented out in the template?
3 participants
This PR is for collaborating on changes to the CNCF Techdocs analysis template(s).