mirror of https://github.com/cncf/techdocs.git
Fix all links in docs and analyses, and rename resources (#248)
This commit is contained in:
Patrice Chalin
GitHub
parent
55eb6c92ba
commit
e06a02dadc
|
|
@ -5,6 +5,12 @@
|
|||
},
|
||||
{
|
||||
"pattern": "^#"
|
||||
},
|
||||
{
|
||||
"pattern": "^https://(www|docs).tremor.rs"
|
||||
},
|
||||
{
|
||||
"pattern": "\\?no-link-check$"
|
||||
}
|
||||
],
|
||||
"timeout": "3s",
|
||||
|
|
|
|||
|
|
@ -26,8 +26,9 @@ The assessment is divided into three sections:
|
|||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Within each section you receive a rating on different criteria. The full
|
||||
definition of each criteria is defined in [the criteria](criteria.md). We
|
||||
recommend reading each criterion’s definition.
|
||||
definition of each criteria is defined in
|
||||
[the criteria](../docs/analysis/criteria.md). We recommend reading each
|
||||
criterion’s definition.
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
@ -44,8 +45,8 @@ recommend reading each criterion’s definition.
|
|||
|
||||
- Documentation is feature complete!
|
||||
- A clear "About" or "What is Contour?" page is missing. It partially exists
|
||||
on (Architecture)[https://projectcontour.io/docs/v1.13.1/architecture/] and
|
||||
(Philosophy)[https://projectcontour.io/resources/philosophy/], but it's hard
|
||||
on [Architecture](https://projectcontour.io/docs/v1.13.1/architecture) and
|
||||
[Philosophy](https://projectcontour.io/resources/philosophy), but it's hard
|
||||
to navigate for a new user.
|
||||
- Task and concept documentation for individual features (configurations and
|
||||
deployment options) are both feature complete.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
# Notary Project Docs Assessment
|
||||
|
||||
Date: 2021-07-31
|
||||
Project: [Notary Project](https://github.com/notaryproject/)
|
||||
Date: 2021-07-31 Project: [Notary Project](https://github.com/notaryproject/)
|
||||
|
||||
## Introduction
|
||||
|
||||
|
|
@ -29,7 +28,8 @@ This assessment is divided into two sections:
|
|||
- **Contributor documentation:** for new and existing contributors to the
|
||||
project
|
||||
|
||||
Each section rates content based on different [criteria](criteria.md).
|
||||
Each section rates content based on different
|
||||
[criteria](../docs/analysis/criteria.md).
|
||||
|
||||
Normally, a **website** section would also be a part of a document assessment,
|
||||
but as there isn't a website for the Notary Project yet, the website assessment
|
||||
|
|
@ -218,7 +218,7 @@ developed?
|
|||
https://github.com/notaryproject/notaryproject/issues/77)
|
||||
- [ ] Develop a maintenance plan for the documentation and its repository
|
||||
- [ ] Follow the
|
||||
[CNCF website guidelines checklist](https://github.com/cncf/techdocs/blob/main/howto/website-guidelines-checklist.md)
|
||||
[CNCF website guidelines checklist](../docs/website-guidelines-checklist.md)
|
||||
for other required elements
|
||||
|
||||
_Note_:
|
||||
|
|
|
|||
|
|
@ -27,8 +27,9 @@ The assessment is divided into three sections:
|
|||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Within each section you receive a rating on different criteria. The full
|
||||
definition of each criteria is defined in [the criteria](criteria.md). We
|
||||
recommend reading each criterion’s definition.
|
||||
definition of each criteria is defined in
|
||||
[Criteria](../docs/analysis/criteria.md). We recommend reading each criterion’s
|
||||
definition.
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,8 @@ The assessment is divided into three sections:
|
|||
project
|
||||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Each section rates content based on different [criteria](criteria.md).
|
||||
Each section rates content based on different
|
||||
[criteria](../docs/analysis/criteria.md).
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,8 @@ The assessment is divided into three sections:
|
|||
project
|
||||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Each section rates content based on different [criteria](criteria.md).
|
||||
Each section rates content based on different
|
||||
[criteria](../docs/analysis/criteria.md).
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
@ -154,7 +155,7 @@ Scale:
|
|||
|
||||
- [This file](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh)
|
||||
is _very_ fragile, as it points to specific files at their
|
||||
`https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh` and
|
||||
<https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh> and
|
||||
seems to have the potential to make the site build succeed but with
|
||||
unpredictable results.
|
||||
- Consider implementing [Hugo Modules](https://gohugo.io/hugo-modules/) to
|
||||
|
|
@ -166,7 +167,7 @@ Scale:
|
|||
**Content creation processes**:
|
||||
|
||||
- Put
|
||||
[this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally)
|
||||
[this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally?no-link-check)
|
||||
directly in the README.md of the website repository, because people are lazy.
|
||||
Kudos on trying to keep everything in one place, however!
|
||||
|
||||
|
|
@ -200,7 +201,7 @@ Scale:
|
|||
[Community repository](https://github.com/fluxcd/community).
|
||||
- Project governance is [clearly documented](https://fluxcd.io/governance/). The
|
||||
community repository also includes information on
|
||||
[Oversight](https://github.com/fluxcd/community/blob/main/OVERSIGHT.md),
|
||||
[governance](https://github.com/fluxcd/community/blob/main/GOVERNANCE.md),
|
||||
[Community roles](https://github.com/fluxcd/community/blob/main/community-roles.md),
|
||||
and more.
|
||||
|
||||
|
|
@ -242,7 +243,7 @@ Scale:
|
|||
fragility, particularly once the original code owners leave the organization.
|
||||
|
||||
- Flux meets and exceeds the
|
||||
[website requirements](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#minimal-website-requirements)
|
||||
[website requirements](../docs/analysis/criteria.md#minimal-website-requirements)
|
||||
for its maturity level, save for the single sourcing requirement as noted
|
||||
above.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,8 @@ The assessment is divided into three sections:
|
|||
project
|
||||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Each section rates content based on different [criteria](criteria.md).
|
||||
Each section rates content based on different
|
||||
[criteria](../docs/analysis/criteria.md).
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
@ -56,7 +57,7 @@ are mentioned in brief, great work!
|
|||
**New user content**:
|
||||
|
||||
We have a great, clearly labelled
|
||||
[Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/)
|
||||
[Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/?no-link-check)
|
||||
page, which is awesome! However, the getting started guide is fairly high level
|
||||
and doesn't answer some of the following questions:
|
||||
|
||||
|
|
@ -97,7 +98,7 @@ as well as where to find them.
|
|||
- **Prepared a miro board:
|
||||
[https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)**
|
||||
|
||||
|
||||
|
||||
|
||||
- There are improvements we could make:
|
||||
- With the collection of guided, step-by-step instructions (tasks, hands-on
|
||||
|
|
|
|||
|
|
@ -6,9 +6,8 @@ tags: porter
|
|||
# Notes
|
||||
|
||||
meeting notes:
|
||||
https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing
|
||||
website: https://getporter.org/
|
||||
repos:
|
||||
https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing
|
||||
website: https://getporter.org/ repos:
|
||||
|
||||
- https://github.com/getporter/porter (main site), site content is in docs/
|
||||
folder
|
||||
|
|
@ -45,7 +44,8 @@ The assessment is divided into three sections:
|
|||
project
|
||||
- **Website:** branding, website structure, and maintainability
|
||||
|
||||
Each section rates content based on different [criteria](criteria.md).
|
||||
Each section rates content based on different
|
||||
[criteria](../docs/analysis/criteria.md).
|
||||
|
||||
## Project documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -47,11 +47,11 @@ Backstage GitHub repo.
|
|||
- Website: https://backstage.io
|
||||
- Documentation: https://backstage.io/docs
|
||||
- Contributor documentation:
|
||||
- https://github.com/backstage/backstage/README.md
|
||||
- https://github.com/backstage/backstage/CONTRIBUTING.md
|
||||
- https://github.com/backstage/backstage/blob/master/README.md
|
||||
- https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md
|
||||
- Website configuration (Docusaurus):
|
||||
https://github.com/backstage/backstage/microsite
|
||||
- Website content: https://github.com/backstage/backstage/docs
|
||||
https://github.com/backstage/backstage/blob/master/microsite
|
||||
- Website content: https://github.com/backstage/backstage/blob/master/docs
|
||||
|
||||
**Out of scope:**
|
||||
|
||||
|
|
@ -581,19 +581,20 @@ Improve compliance in these areas:
|
|||
|
||||
[backstage-backstage]: https://github.com/backstage/backstage
|
||||
[backstage-community]: https://backstage.io/community
|
||||
[backstage-contrib]: https://github.com/backstage/backstage/CONTRIBUTING.md
|
||||
[backstage-contrib]:
|
||||
https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md
|
||||
[backstage-demo]:
|
||||
https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned
|
||||
[backstage-discussion]: https://github.com/backstage/backstage/discussions
|
||||
[backstage-discussion]: https://discord.gg/backstage-687207715902193673
|
||||
[backstage-doc-contrib]:
|
||||
https://backstage.io/docs/getting-started/getting-involved#write-documentation-or-improve-the-website
|
||||
https://backstage.io/docs/contribute/getting-involved#write-documentation-or-improve-the-website
|
||||
[backstage-doc-deployment]: https://backstage.io/docs/deployment/
|
||||
[backstage-doc-getting-started]: https://backstage.io/docs/getting-started/
|
||||
[backstage-doc-rn]: https://backstage.io/docs/releases/v1.17.0
|
||||
[backstage-github-community]: https://github.com/backstage/community
|
||||
[backstage-github-project]: https://github.com/backstage
|
||||
[backstage-governance]:
|
||||
https://github.com/backstage/backstage/blob/master/GOVERNANCE.md
|
||||
https://github.com/backstage/community/blob/main/GOVERNANCE.md
|
||||
[backstage-insights-summary]: ./backstage-insights-summary.md
|
||||
[backstage-issues]: https://github.com/backstage/backstage/issues
|
||||
[backstage-io-overview-benefits]:
|
||||
|
|
@ -603,11 +604,9 @@ Improve compliance in these areas:
|
|||
[backstage-microsite]:
|
||||
https://github.com/backstage/backstage/tree/master/microsite
|
||||
[clotributor]: https://clotributor.dev/
|
||||
[cncf-doc-criteria]: ../criteria.md
|
||||
[cncf-doc-criteria]:
|
||||
https://github.com/cncf/techdocs/blob/main/assessments/criteria.md
|
||||
[cncf-docs-howto]:
|
||||
https://github.com/cncf/techdocs/blob/main/assessments/howto.md
|
||||
[cncf-doc-criteria]: ../../docs/analysis/criteria.md
|
||||
[cncf-doc-criteria]: ../../docs/analysis/criteria.md
|
||||
[cncf-docs-howto]: ../../docs/analysis/howto.md
|
||||
[cncf-maturity-stages]:
|
||||
https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
|
||||
[cncf-servicedesk]: https://servicedesk.cncf.io
|
||||
|
|
@ -628,7 +627,7 @@ Improve compliance in these areas:
|
|||
|
||||
[contrib-doc-rec]: #recommendations-contributor-documentation
|
||||
[contributor-doc]: #contributor-documentation
|
||||
[doc-survey]: ./Backstage%20doc%20survey.csv
|
||||
[doc-survey]: backstage-doc-survey.csv
|
||||
[implementation]: #implementation
|
||||
[info-arch-recommend]: #recommendations
|
||||
[proj-doc-comments]: #comments-project-documentation
|
||||
|
|
|
|||
|
|
@ -58,20 +58,20 @@ Readers interested only in actionable improvements can skip to the
|
|||
[implementation recommendations](./in-toto-implementation.md). For more context,
|
||||
read the recommendations for each of the three areas of analysis:
|
||||
|
||||
- [Project documentation recommendations](./assessments#recommendations)
|
||||
- [Project documentation recommendations](#recommendations-1)
|
||||
|
||||
- [Contributor documentation recommendations](./assessments#recommendations-1)
|
||||
- [Contributor documentation recommendations](#recommendations-2)
|
||||
|
||||
- [Website recommendations](./assessments#recommendations-2)
|
||||
- [Website recommendations](#recommendations-3)
|
||||
|
||||
Readers interested in the current state of the documentation and the reasoning
|
||||
behind the recommendations should start with the analyses:
|
||||
|
||||
- [Project documentation](./assessments#project-documentation-analysis)
|
||||
- [Project documentation](#project-documentation-analysis)
|
||||
|
||||
- [Contributor documentation](./assessments#contributor-documentation-analysis)
|
||||
- [Contributor documentation](#contributor-documentation-analysis)
|
||||
|
||||
- [Website](./assessments#website-analysis)
|
||||
- [Website](#website-analysis)
|
||||
|
||||
# Analysis and Recommendations
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ sync.
|
|||
The Contributing and Governance files do not mention changes or additions to
|
||||
documentation as potential areas of contribution.
|
||||
|
||||
### Recommendations
|
||||
### Recommendations 1
|
||||
|
||||
**Information Architecture**
|
||||
|
||||
|
|
@ -235,7 +235,7 @@ contribution (such as docs).
|
|||
**Project governance documentation**: Clearly described and discoverable on
|
||||
GOVERNANCE page.
|
||||
|
||||
### Recommendations
|
||||
### Recommendations 2
|
||||
|
||||
**Communication methods documented**
|
||||
|
||||
|
|
@ -333,7 +333,7 @@ correctly.
|
|||
**Intra-site / local search**: There is no site map or search mechanism; the
|
||||
only navigation is through a minimal menu bar.
|
||||
|
||||
### Recommendations
|
||||
### Recommendations 3
|
||||
|
||||
**Meets min website req. (for Incubating)**, **Intra-site / local search**
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ repurposed as the new overall **Doc home page**.
|
|||
|
||||
- [ ] To be immediately useful, the landing page should provide a _top-level
|
||||
roadmap_ to existing docs. See
|
||||
[Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
|
||||
[Survey of existing doc](survey-of-existing-doc.md)
|
||||
|
||||
This is a necessary step in raising the maturity level of this project. The
|
||||
roadmap should initially describe and provide access to:
|
||||
|
|
@ -72,9 +72,9 @@ A basic intro, possibly suitable for evaluators, is already linked directly from
|
|||
the [home page About tab](https://in-toto.io/in-toto/). The short intro links to
|
||||
the
|
||||
[latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md),
|
||||
which contains a more comprehensive overview. (NOTE: The
|
||||
[PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf)
|
||||
is broken. This should be fixed or removed.)
|
||||
which contains a more comprehensive overview. (NOTE: The PDF link to the stable
|
||||
spec, `https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf`, is broken.
|
||||
This should be fixed or removed.)
|
||||
|
||||
- [ ] Initially, transfer the tech overview content from the Specification into
|
||||
a top-level Technical Overview document in RTD, and link as "Read more..."
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@
|
|||
## Organizational principles
|
||||
|
||||
Review the
|
||||
[CNCF website design guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md)
|
||||
for project home page and architecture recommendations. Consult with CNCF
|
||||
TechDocs or other technical documentation specialists to develop an appropriate
|
||||
[CNCF website design guidelines](../../docs/website-guidelines-checklist.md) for
|
||||
project home page and architecture recommendations. Consult with CNCF TechDocs
|
||||
or other technical documentation specialists to develop an appropriate
|
||||
information architecture based on different user roles and their specific tasks
|
||||
and information needs.
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ following general plan.
|
|||
menu.
|
||||
|
||||
b. Create a **Getting Started** page on the web site from the existing README
|
||||
content in the [main repo](https://github.com/in-toto/in-toto.README.md).
|
||||
content in the [main repo](https://github.com/in-toto/in-toto).
|
||||
|
||||
c. Link **Getting Started** as the first menu item in the **Get started**
|
||||
menu (currently the first item is a link to a demo).
|
||||
|
|
@ -85,7 +85,7 @@ following general plan.
|
|||
the website, as:
|
||||
|
||||
- [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview)
|
||||
(compare content to https://in-toto.io/in-toto/README and current website
|
||||
(compare content to <https://in-toto.io/in-toto> and current website
|
||||
About - create versions of increasing depth to address to specific
|
||||
audiences)
|
||||
- [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology)
|
||||
|
|
@ -132,8 +132,8 @@ following general plan.
|
|||
the git repo structure.
|
||||
|
||||
1.1 Create a _top-level roadmap_ to
|
||||
[existing docs](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
|
||||
at the location decided on for the Doc home page.
|
||||
[existing docs](survey-of-existing-doc.md) at the location decided on for the
|
||||
Doc home page.
|
||||
|
||||
1.2 Move the Description and pointer to the Python Reference implementation
|
||||
to an **Implementations** section, and move the RTD reference docs for it
|
||||
|
|
@ -179,9 +179,9 @@ following general plan.
|
|||
from the [home page About tab](https://in-toto.io/in-toto/). The short intro
|
||||
links to the
|
||||
[latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md),
|
||||
which contains a more comprehensive overview. (NOTE: The
|
||||
[PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf)
|
||||
is broken. This should be fixed or removed.)
|
||||
which contains a more comprehensive overview. (NOTE: The PDF link to the
|
||||
stable spec, `https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf` is
|
||||
broken. This should be fixed or removed.)
|
||||
|
||||
3.1 Initially, transfer the tech overview content from the Specification into
|
||||
a top-level Technical Overview document in RTD, and link as "Read more..."
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ Netlify platform. The site's code is stored on the etcd GitHub repo.
|
|||
- Documentation: https://etcd.io/docs
|
||||
- Website repo: https://github.com/etcd-io/website
|
||||
- Main project contributor info: https://github.com/etcd-io/etcd
|
||||
- Demo server: http://play.etcd.io
|
||||
- Demo server: [http://play.etcd.io][demo server]
|
||||
|
||||
**Out of scope:**
|
||||
|
||||
|
|
@ -207,22 +207,22 @@ Benchmarks for down-level versions are available in the current documentation.
|
|||
It's not clear why these old benchmarks haven't been removed from the
|
||||
documentation.
|
||||
|
||||
There is an example **installation** on the
|
||||
[etcd Play](http://play.etcd.io/install) server that presents "an example
|
||||
workflow to install and deploy etcd." This page consists of a form containing
|
||||
parameters (with no explanation of each parameter other than the label) followed
|
||||
by a CLI script that varies depending on the installation type you choose.
|
||||
Presumably you're supposed to run the script to do the install, but there are no
|
||||
clear task instructions at all. It's not clear how this is useful. Novice users
|
||||
will have a hard time with this. Also, why is this information on the demo
|
||||
server at all? Users should be referred to an installation procedure in the
|
||||
documentation. If this represents a separate, automated installation workflow it
|
||||
should be offered as a procedure in the user doc.
|
||||
There is an example **installation** on the [etcd Play][demo server] server that
|
||||
presents "an example workflow to install and deploy etcd." This page consists of
|
||||
a form containing parameters (with no explanation of each parameter other than
|
||||
the label) followed by a CLI script that varies depending on the installation
|
||||
type you choose. Presumably you're supposed to run the script to do the install,
|
||||
but there are no clear task instructions at all. It's not clear how this is
|
||||
useful. Novice users will have a hard time with this. Also, why is this
|
||||
information on the demo server at all? Users should be referred to an
|
||||
installation procedure in the documentation. If this represents a separate,
|
||||
automated installation workflow it should be offered as a procedure in the user
|
||||
doc.
|
||||
|
||||
### New user content
|
||||
|
||||
There is a single paragraph on the [website][etcd-io] landing page with a "Learn
|
||||
more" link that goes to the current documetation table of contents (ToC). It
|
||||
more" link that goes to the current documentation table of contents (ToC). It
|
||||
would be better to link to an overview page that laid out learning paths for
|
||||
different users ("Start here").
|
||||
|
||||
|
|
@ -383,9 +383,8 @@ In general, confine release-specific discussion to the Release Notes.
|
|||
Remove benchmarks for down-level versions in the current documentation if
|
||||
they're no longer relevant.
|
||||
|
||||
Consider removing the installation example from the
|
||||
[etcd Play](http://play.etcd.io/install) server and pointing the user to the
|
||||
documentation's installation instructions.
|
||||
Consider removing the installation example from the [etcd Play][demo server]
|
||||
server and pointing the user to the documentation's installation instructions.
|
||||
|
||||
### New user content
|
||||
|
||||
|
|
@ -450,8 +449,8 @@ Audit the documentation for non-inclusive language. See the
|
|||
# Contributor documentation
|
||||
|
||||
etcd is a **graduated** project of CNCF. This means that the project should have
|
||||
[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
standards for contributor documentation.
|
||||
[_very high_](../../docs/analysis/criteria.md) standards for contributor
|
||||
documentation.
|
||||
|
||||
| Criterion | Rating (1-5) |
|
||||
| ----------------------------------------- | ------------------------------ |
|
||||
|
|
@ -533,8 +532,7 @@ No recommnendations.
|
|||
# Website
|
||||
|
||||
etcd is a **graduated** project of CNCF. This means that the project should have
|
||||
[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
standards for documentation.
|
||||
[_very high_](../../docs/analysis/criteria.md) standards for documentation.
|
||||
|
||||
| Criterion | Rating (1-5) |
|
||||
| ------------------------------------------- | ------------------------------ |
|
||||
|
|
@ -667,7 +665,7 @@ in the OWNERS file in the repo. Approvers and reviewers are listed.
|
|||
The website is accessible via **HTTPS**. Requests using **HTTP** are properly
|
||||
redirected to the **HTTPS** URLs.
|
||||
|
||||
The [demo server][demo-server] uses unsecured HTTP.
|
||||
The [demo server][] uses unsecured HTTP.
|
||||
|
||||
## Recommendations
|
||||
|
||||
|
|
@ -710,25 +708,24 @@ No recommendations.
|
|||
|
||||
### Other
|
||||
|
||||
Consider securing the [demo server][demo-server] using HTTPS.
|
||||
Consider securing the [demo server][] using HTTPS.
|
||||
|
||||
<!--- References --->
|
||||
|
||||
[etcd-io]: https://etcd.io
|
||||
[cncf-doc-criteria]: ../criteria.md
|
||||
[cncf-doc-criteria]: ../../docs/analysis/criteria.md
|
||||
[implementation-doc]: ./etcd-implementation.md
|
||||
[proj-doc]: ../criteria.md#project-documentation
|
||||
[contributor-doc]: ../criteria.md/#contributor-documentation
|
||||
[website]: ../criteria.md/#website
|
||||
[proj-doc]: ../../docs/analysis/criteria.md#project-documentation
|
||||
[contributor-doc]: ../../docs/analysis/criteria.md#contributor-documentation
|
||||
[website]: ../../docs/analysis/criteria.md#website
|
||||
[etcd-issues]: ./etcd-issues.md
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
[inclusive-naming]: https://inclusivenaming.org
|
||||
[install-check]: https://etcd.io/docs/v3.5/install/#installation-check
|
||||
[website-min-reqs]:
|
||||
https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations
|
||||
[assess-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md
|
||||
[website-guidelines]:
|
||||
https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md
|
||||
[assess-howto]: ../../docs/analysis/howto.md
|
||||
[website-guidelines]: ../../docs/website-guidelines-checklist.md
|
||||
[cncf-servicedesk]: https://servicedesk.cncf.io
|
||||
[archiving-repo]:
|
||||
https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories
|
||||
|
|
@ -736,7 +733,7 @@ Consider securing the [demo server][demo-server] using HTTPS.
|
|||
[etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md
|
||||
[etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions
|
||||
[etcd-govern]: https://github.com/etcd-io/etcd/blob/main/GOVERNANCE.md
|
||||
[demo-server]: http://play.etcd.io
|
||||
[demo server]: http://play.etcd.io?no-link-check
|
||||
[github-etcd-etcd]: https://github.com/etcd-io/etcd
|
||||
[etcdio-triage]: https://etcd.io/docs/v3.5/triage/
|
||||
[doc-optimalclustersize-23]:
|
||||
|
|
|
|||
|
|
@ -75,7 +75,7 @@ These probably include:
|
|||
|
||||
- _Evaluator_: Someone trying to determine whether etcd is appropriate for their
|
||||
product, project, or organization.
|
||||
- _Admin or Operator_: Someone reponsible for setting up and maintaining a
|
||||
- _Admin or Operator_: Someone responsible for setting up and maintaining a
|
||||
standalone (not installed as the backstore for Kubernetes) production etcd
|
||||
service.
|
||||
- _Kubernetes Admin_: Someone responsible for installing and maintaining a
|
||||
|
|
@ -314,4 +314,4 @@ Release notes should include:
|
|||
|
||||
[etcd-analysis]: ./etcd-analysis.md
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
[access-tutorial]: https://etcd.io/docs/v3.5/tutorials/how-to-access-etcd/
|
||||
[access-tutorial]: https://github.com/etcd-io/website/issues/790
|
||||
|
|
|
|||
|
|
@ -73,14 +73,15 @@ the CLI".
|
|||
## Issue: Write installation instructions for Kubernetes
|
||||
|
||||
Write the procedure
|
||||
[Installation as part of Kubernetes installation](install/#installation-as-part-of-kubernetes-installation),
|
||||
[Installation as part of Kubernetes installation](https://etcd.io/docs/v3.5/install/#installation-as-part-of-kubernetes-installation),
|
||||
or link to Kubernetes documentation that includes etcd installation as
|
||||
backstore. Explain and fill in (on the etcd docs page) any gaps in the
|
||||
procedure.
|
||||
|
||||
## Issue: Write Linux installation instructions
|
||||
|
||||
Write [installation instructions for Linux](install/#linux).
|
||||
Write
|
||||
[installation instructions for Linux](https://etcd.io/docs/v3.5/install/#linux).
|
||||
|
||||
## Issue: Update quickstart and new user workflows
|
||||
|
||||
|
|
@ -397,4 +398,4 @@ each path. If such a guide isn't needed, then remove this page.
|
|||
|
||||
[etcd-analysis]: ./etcd-analysis.md
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
[access-tutorial]: https://etcd.io/docs/v3.5/tutorials/how-to-access-etcd/
|
||||
[access-tutorial]: https://github.com/etcd-io/website/issues/790
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ Netlify platform. The site's code is stored on the KEDA GitHub repo.
|
|||
- Website: https://keda.sh
|
||||
- Documentation: https://keda.sh/docs
|
||||
- Website repo: https://github.com/kedacore/keda-docs
|
||||
- Governance repo: https://github.com/kedacore/governanace
|
||||
- Governance repo: https://github.com/kedacore/governance
|
||||
- Main project contributor info: https://github.com/kedacore/keda
|
||||
|
||||
**Out of scope:**
|
||||
|
|
@ -70,8 +70,7 @@ concern:
|
|||
includes branding, website structure, and maintainability
|
||||
|
||||
Each section begins with summary ratings based on a rubric with appropriate
|
||||
[criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
for the section, then proceeds to:
|
||||
[criteria](../../docs/analysis/criteria.md) for the section, then proceeds to:
|
||||
|
||||
- **Comments**: observations about the existing documentation, with a focus on
|
||||
how it does or does not help KEDA users achieve their goals.
|
||||
|
|
@ -83,7 +82,7 @@ breaks the recommendations down into concrete actions that can be implemented by
|
|||
project contributors. Its focus is on drilling down to specific, achievable work
|
||||
that can be completed in constrained blocks of time. Ultimately, the
|
||||
implementation items should be tracked as a series of Github
|
||||
[issues]((./keda-issues.md).
|
||||
[issues](keda-issues.md).
|
||||
|
||||
## How to use this document
|
||||
|
||||
|
|
@ -99,9 +98,7 @@ to their area of concern:
|
|||
- [Website and documentation infrastructure](#website)
|
||||
|
||||
Examples of CNCF documentation that demonstrate the analysis criteria are linked
|
||||
from the
|
||||
[criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
specification.
|
||||
from the [criteria](../../docs/analysis/criteria.md) specification.
|
||||
|
||||
### Recommendations, requirements, and best practices
|
||||
|
||||
|
|
@ -119,8 +116,7 @@ copyright and licensing issues.
|
|||
# Project documentation
|
||||
|
||||
KEDA is a **graduated** project of CNCF. This means that the project should have
|
||||
[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
standards for documentation.
|
||||
[_very high_](../../docs/analysis/criteria.md) standards for documentation.
|
||||
|
||||
| Criterion | Rating (1-5) |
|
||||
| -------------------------- | --------------------- |
|
||||
|
|
@ -294,8 +290,8 @@ Remove non-inclusive language throughout the documentation as recommended on the
|
|||
# Contributor documentation
|
||||
|
||||
KEDA is a **graduated** project of CNCF. This means that the project should have
|
||||
[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
standards for contributor documentation.
|
||||
[_very high_](../../docs/analysis/criteria.md) standards for contributor
|
||||
documentation.
|
||||
|
||||
| Criterion | Rating (1-5) |
|
||||
| ----------------------------------------- | ------------------------------ |
|
||||
|
|
@ -363,8 +359,7 @@ No recommendations.
|
|||
# Website
|
||||
|
||||
KEDA is a **graduated** project of CNCF. This means that the project should have
|
||||
[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md)
|
||||
standards for documentation.
|
||||
[_very high_](../../docs/analysis/criteria.md) standards for documentation.
|
||||
|
||||
| Criterion | Rating (1-5) |
|
||||
| ------------------------------------------- | ------------------------------ |
|
||||
|
|
@ -407,15 +402,15 @@ sandbox, incubating, graduated and archived.
|
|||
|
||||
| Maturity | Requirement | Met? |
|
||||
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| Sandbox | Majority of [Website guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) satisfied | Yes |
|
||||
| Sandbox | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md) [cncf-servicedesk] completed. | Yes |
|
||||
| Sandbox | Majority of [Website guidelines](../../docs/website-guidelines-checklist.md) satisfied | Yes |
|
||||
| Sandbox | [Docs assessment](../../docs/analysis/howto.md) [cncf-servicedesk] completed. | Yes |
|
||||
| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes |
|
||||
| Incubating | All [Website guidelines](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#website) satisfied | Yes |
|
||||
| Incubating | All [Website guidelines](../../docs/analysis/criteria.md#website) satisfied | Yes |
|
||||
| Incubating | Request docs (re-)assessment through CNCF [service desk](https://servicedesk.cncf.io/) | Yes |
|
||||
| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No |
|
||||
| Incubating | **Project doc**: Hosted directly | Yes |
|
||||
| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes |
|
||||
| Graduated | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md): all assessment follow-through actions are complete | No |
|
||||
| Graduated | [Docs assessment](../../docs/analysis/howto.md): all assessment follow-through actions are complete | No |
|
||||
| Graduated | **Project doc** fully addresses needs of key stakeholders | No - new user doc needs improvement |
|
||||
| Archived | The website repo is in an [archived state](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) | n/a |
|
||||
| Archived | Archived status of the project is obvious to site visitors | n/a |
|
||||
|
|
|
|||
|
|
@ -60,22 +60,22 @@ In general, follow these principles when reorganizing the documentation:
|
|||
|
||||
Here is a proposed outline for the tech doc Table of Contents:
|
||||
|
||||
- [KEDA Concepts](/docs/2.13/concepts/)
|
||||
- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/)
|
||||
- What is KEDA?
|
||||
- How KEDA works
|
||||
- KEDA Architecture
|
||||
- KEDA Custom Resources (CRDs)
|
||||
- [Scaling Deployments, StatefulSets & Custom Resources](/docs/2.13/concepts/scaling-deployments/)
|
||||
- [Scaling Deployments, StatefulSets & Custom Resources](https://keda.sh/docs/2.13/concepts/scaling-deployments/)
|
||||
- Overview
|
||||
- Scaling Deployments and Stateful Sets
|
||||
- Scaling Custom Resources
|
||||
- [Scaling Jobs](/docs/2.13/concepts/scaling-jobs/)
|
||||
- [Authentication](/docs/2.13/concepts/authentication/)
|
||||
- [External Scalers](/docs/2.13/concepts/external-scalers/)
|
||||
- [Admission Webhooks](/docs/2.13/concepts/admission-webhooks/)
|
||||
- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA
|
||||
Documentation" heading)
|
||||
- [Deploying KEDA](/docs/2.13/deploy/)
|
||||
- [Scaling Jobs](https://keda.sh/docs/2.13/concepts/scaling-jobs/)
|
||||
- [Authentication](https://keda.sh/docs/2.13/concepts/authentication/)
|
||||
- [External Scalers](https://keda.sh/docs/2.13/concepts/external-scalers/)
|
||||
- [Admission Webhooks](https://keda.sh/docs/2.13/concepts/admission-webhooks/)
|
||||
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename
|
||||
current "KEDA Documentation" heading)
|
||||
- [Deploying KEDA](https://keda.sh/docs/2.13/deploy/)
|
||||
- Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements)
|
||||
- [Deploying with Helm](#helm)
|
||||
- [Installing](#install)
|
||||
|
|
@ -92,56 +92,57 @@ Here is a proposed outline for the tech doc Table of Contents:
|
|||
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
|
||||
get started on - something like
|
||||
https://github.com/kedacore/sample-hello-world-azure-functions)
|
||||
- [Using KEDA or Operator Guide](/docs/2.13/operate/) (rename current "Operate")
|
||||
- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename
|
||||
current "Operate")
|
||||
- How to set up a scaler (a more detailed procedure than the example used in
|
||||
Getting Started)
|
||||
- Usage Scenarios
|
||||
- [Scaling with RabbitMQ and Go](https://github.com/kedacore/sample-go-rabbitmq)
|
||||
- [Scaling with Azure Functions and Kafka on Openshift 4](https://github.com/kedacore/sample-azure-functions-on-ocp4)
|
||||
- ... and so on.
|
||||
- [Admission Webhooks](/docs/2.13/operate/admission-webhooks/)
|
||||
- [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/)
|
||||
- Prevention Rules
|
||||
(https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
|
||||
- Validation Enforcement
|
||||
- [Cluster](/docs/2.13/operate/cluster/) - Except sections that are purely
|
||||
reference info, for example:
|
||||
- [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - Except sections that
|
||||
are purely reference info, for example:
|
||||
- https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility
|
||||
- https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity
|
||||
- https://keda.sh/docs/2.13/operate/cluster/#firewall
|
||||
- [Integrating with OpenTelemetry Collector (Experimental)](/docs/2.13/operate/opentelemetry/)
|
||||
- [Integrating with Prometheus](/docs/2.13/operate/prometheus/)
|
||||
- [Using the KEDA Metrics Server](/docs/2.13/operate/metrics-server/)
|
||||
- [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/operate/opentelemetry/)
|
||||
- [Integrating with Prometheus](https://keda.sh/docs/2.13/operate/prometheus/)
|
||||
- [Using the KEDA Metrics Server](https://keda.sh/docs/2.13/operate/metrics-server/)
|
||||
- [Querying Metrics](https://keda.sh/docs/2.13/operate/metrics-server/#querying-metrics-exposed-by-keda-metrics-server)
|
||||
- [Getting Metric Names](https://keda.sh/docs/2.13/operate/metrics-server/#how-to-get-metric-names-from-scaledobject)
|
||||
- [Security](/docs/2.13/operate/security/)
|
||||
- [Migrating to a new release](/docs/2.13/migration/) (current "Migration
|
||||
Guide")
|
||||
- [Security](https://keda.sh/docs/2.13/operate/security/)
|
||||
- [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current
|
||||
"Migration Guide")
|
||||
- Caching Metrics
|
||||
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics)
|
||||
- Pausing Autoscaling of deployments
|
||||
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling)
|
||||
- Pausing Autoscaling of jobs
|
||||
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling)
|
||||
- [Troubleshooting](/docs/2.13/concepts/troubleshooting/,
|
||||
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/,
|
||||
/docs/2.13/troubleshooting/)
|
||||
- Reference
|
||||
- [Authentication Providers](/docs/2.13/authentication-providers/)
|
||||
- [AWS (IRSA) Pod Identity Webhook](/docs/2.13/authentication-providers/aws/)
|
||||
- [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/)
|
||||
- [AWS (IRSA) Pod Identity Webhook](https://keda.sh/docs/2.13/authentication-providers/aws/)
|
||||
- ...
|
||||
- [Secret](/docs/2.13/authentication-providers/secret/)
|
||||
- [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/)
|
||||
- Scaled Object specification (from "Concepts";
|
||||
https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec)
|
||||
- ScaledJob specification
|
||||
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
|
||||
- [Events](/docs/2.13/operate/events/)
|
||||
- [Events](https://keda.sh/docs/2.13/operate/events/)
|
||||
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
|
||||
- ...
|
||||
- [FAQ](/docs/2.13/faq/)
|
||||
- [FAQ](https://keda.sh/docs/2.13/faq/)
|
||||
- Glossary
|
||||
- [Scalers](/docs/2.13/scalers/)
|
||||
- [ActiveMQ](/docs/2.13/scalers/activemq/)
|
||||
- [Scalers](https://keda.sh/docs/2.13/scalers/)
|
||||
- [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/)
|
||||
- ...
|
||||
- [Solr](/docs/2.13/scalers/solr/)
|
||||
- [Solr](https://keda.sh/docs/2.13/scalers/solr/)
|
||||
|
||||
Among other things, the reorganization includes these changes:
|
||||
|
||||
|
|
@ -183,10 +184,11 @@ following outline, extracted from the proposed outline in
|
|||
[Reorganize the Table of Contents](#reorganize-the-table-of-contents), has been
|
||||
annotated to illustrate this point:
|
||||
|
||||
- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA
|
||||
Documentation" heading) _Make the new user entry point obvious_
|
||||
- [Deploying KEDA](/docs/2.13/deploy/) _This is analogous to "Install" for
|
||||
application software or a plugin. It's the starting point for a new user._
|
||||
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename
|
||||
current "KEDA Documentation" heading) _Make the new user entry point obvious_
|
||||
- [Deploying KEDA](https://keda.sh/docs/2.13/deploy/) _This is analogous to
|
||||
"Install" for application software or a plugin. It's the starting point for
|
||||
a new user._
|
||||
- [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements)
|
||||
_Make sure the new user has their tools gathered up before they start.
|
||||
This reduces frustration. Next, what is the advantage of one deployment
|
||||
|
|
|
|||
|
|
@ -70,10 +70,11 @@ existing pages that can be used as-is or provide a starting point. Pages with
|
|||
multiple procedures (for example, the "Deploying KEDA" page) should be split
|
||||
into multiple pages, one for each procedure.
|
||||
|
||||
- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA
|
||||
Documentation" heading) _Make the new user entry point obvious._
|
||||
- [Deploying KEDA](/docs/2.13/deploy/) _This is analogous to "Install" for
|
||||
application software or a plugin. It's the starting point for a new user._
|
||||
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename
|
||||
current "KEDA Documentation" heading) _Make the new user entry point obvious._
|
||||
- [Deploying KEDA](https://keda.sh/docs/2.13/deploy/) _This is analogous to
|
||||
"Install" for application software or a plugin. It's the starting point for
|
||||
a new user._
|
||||
- Overview _Briefly explain the differences between installation methods.
|
||||
What is the advantage of one deployment method over another? If the choice
|
||||
is not completely arbitrary, explain the differences here to help the new
|
||||
|
|
|
|||
|
|
@ -14,8 +14,8 @@ The goals of a CNCF technical documentation analysis are to:
|
|||
- Recommends a program of key improvements with the largest return on
|
||||
investment. These improvements are documented as _recommendations_ in the
|
||||
analysis document and expanded in a companion
|
||||
[implementation plan](../docs/analysis/resources/implementation-template.md)
|
||||
and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md).
|
||||
[implementation plan](../docs/analysis/templates/implementation.md) and
|
||||
[issues backlog](../docs/analysis/templates/umbrella-issue.md).
|
||||
|
||||
## Audience
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ Examples:
|
|||
|
||||
- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly
|
||||
documented maintainers)
|
||||
- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/
|
||||
- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md
|
||||
|
||||
### Inclusive language
|
||||
|
||||
|
|
@ -181,8 +181,8 @@ maturity levels so, for example, incubating projects must satisfy the
|
|||
requirements for sandbox projects.
|
||||
|
||||
- **Sandbox**
|
||||
- [Website guidelines](../../docs/website-guidelines-checklist.md): majority
|
||||
of the guidelines are satisfied
|
||||
- [Website guidelines](../website-guidelines-checklist.md): majority of the
|
||||
guidelines are satisfied
|
||||
- [Docs assessment][]: consider [submitting a request][service desk] for an
|
||||
assessment as early as possible to avoid documentation and website rework.
|
||||
- **Project documentation** may or may not be present -- it is acceptable at
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@ The goals of a CNCF technical documentation analysis are to:
|
|||
- Recommends a program of key improvements with the largest return on
|
||||
investment. These improvements are documented as _recommendations_ in the
|
||||
analysis document and expanded in a companion
|
||||
[implementation plan](./resources/implementation-template.md) and
|
||||
[issues backlog](./resources/umbrella-issue-template.md).
|
||||
[implementation plan](./templates/implementation.md) and
|
||||
[issues backlog](./templates/umbrella-issue.md).
|
||||
|
||||
## Doing a Tech Docs Analysis
|
||||
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
|
||||
This directory contains templates for analyzing a CNCF project's documentation.
|
||||
|
||||
## Contents
|
||||
|
||||
Use the templates in this directory to perform a documentation analysis for
|
||||
CNCF. These materials provide:
|
||||
|
||||
|
|
@ -14,8 +12,6 @@ CNCF. These materials provide:
|
|||
- Emphasis on effective documentation that serves all users associated with the
|
||||
project.
|
||||
|
||||
Resources for completing a documentation analysis, including a [how-to][] guide
|
||||
and analysis [criteria][], are in the `docs` directory.
|
||||
|
||||
[how-to]: ../howto.md
|
||||
[criteria]: ../criteria.md
|
||||
Resources for completing a documentation analysis, including a
|
||||
[how-to](../howto.md) guide and analysis [criteria](../criteria.md), are in the
|
||||
`docs` directory.
|
||||
|
|
@ -542,14 +542,14 @@ We evaluate on the following:
|
|||
|
||||
<!--- References --->
|
||||
|
||||
[project-website]: _PROJECT-WEBSITE_
|
||||
[project-doc-website]: _PROJECT-DOC-URL_
|
||||
[project-website]: #?_PROJECT-WEBSITE_
|
||||
[project-doc-website]: #?_PROJECT-DOC-URL_
|
||||
[criteria-doc]: ../criteria.md
|
||||
[implementation-template]: ./implementation-template.md
|
||||
[implementation-template]: ./implementation.md
|
||||
[issues-template]: ./issue-template.md
|
||||
[umbrella-template]: ./umbrella-issue-template.md
|
||||
[implementation-doc]: ./_PROJECT_-implementation.md
|
||||
[issues-doc]: ./_PROJECT_-issues.md
|
||||
[umbrella-template]: ./umbrella-issue.md
|
||||
[implementation-doc]: #?_PROJECT_-implementation.md
|
||||
[issues-doc]: #?_PROJECT_-issues.md
|
||||
[project-heading]: #project-documentation
|
||||
[contributor-heading]: #contributor-documentation
|
||||
[website-heading]: #website
|
||||
|
|
@ -21,7 +21,8 @@ Type:
|
|||
|
||||
This issue tracks recommended changes resulting from an analysis of the etcd
|
||||
documentation commissioned by CNCF. The analysis and supporting documents are
|
||||
here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/
|
||||
here: <https://github.com/cncf/techdocs/tree/main/analyses> under
|
||||
`00NN-project`.
|
||||
|
||||
# Possible Implementation
|
||||
|
||||
|
|
@ -29,7 +30,8 @@ here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/
|
|||
|
||||
Related material in the current doc:
|
||||
|
||||
- https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials
|
||||
- For example,
|
||||
`https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials`
|
||||
|
||||
<!-- Describe in detail a suggested way to achieve the goals of the issue. This should be specific enough to provide a contributor with a recipe for making the change; however, the contributor should feel free to solve the problem differently if they have an idea how it should be done. -->
|
||||
|
||||
|
|
@ -13,11 +13,11 @@ tags: _PROJECT_
|
|||
|
||||
This issue tracks recommended changes resulting from an analysis of the
|
||||
_PROJECT_ documentation commissioned by CNCF. The analysis and supporting
|
||||
documents are here:
|
||||
https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/
|
||||
documents are here: <https://github.com/cncf/techdocs/tree/main/analyses> under
|
||||
`00NN-project`.
|
||||
|
||||
The CNCF etcd documentation effort is tracked in the CNCF Tech Docs repo:
|
||||
https://github.com/cncf/techdocs/issues/NNN
|
||||
The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
|
||||
<https://github.com/cncf/techdocs/issues>
|
||||
|
||||
# Issues
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ website and technical documentation.
|
|||
|
||||
<!-- Summarize the documentation changes prescribed by this issue. Use enough detail to estimate the scope of the issue. Fine-grained detail can go in the issue itself. In the GitHub umbrella issue, link to the sub-issue using a Markdown checkbox as shown below. -->
|
||||
|
||||
- [ ] https://github.com/project/repo/issues/NNN
|
||||
- [ ] `https://github.com/_PROJECT_/repo/issues/NNN`
|
||||
|
||||
## Issue: Item 2
|
||||
|
||||
|
|
@ -8,7 +8,7 @@
|
|||
"_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
|
||||
"_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
|
||||
"check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
|
||||
"check:links": "bash -c 'for f in *.md docs/*.md; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'",
|
||||
"check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'",
|
||||
"check:spelling": "npx cspell --no-progress -c .cspell.yml *.md",
|
||||
"check": "npm run seq -- $(npm run -s _list:check:*)",
|
||||
"fix:format": "npm run _check:format -- --write",
|
||||
|
|
|
|||
Loading…
Reference in New Issue