diff --git a/.markdown-link-check.json b/.markdown-link-check.json index f2239ee..b315dfe 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -5,6 +5,12 @@ }, { "pattern": "^#" + }, + { + "pattern": "^https://(www|docs).tremor.rs" + }, + { + "pattern": "\\?no-link-check$" } ], "timeout": "3s", diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index 5cb981f..76dfa25 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -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. diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index 9ddcc4f..5951046 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -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_: diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index ed9a954..c4cba3b 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -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 diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 7365447..951cb92 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -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 diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index c24b545..591c777 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -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 + 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. diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index ec69e59..3eee0ba 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -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=/)** - ![information_architecture](/images/gapi_info_arch.png) + ![information_architecture](../images/gapi_info_arch.png) - There are improvements we could make: - With the collection of guided, step-by-step instructions (tasks, hands-on diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index b13f95d..fbad169 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -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 diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md index 65675b6..2ca64a2 100644 --- a/analyses/0008-backstage/backstage-analysis.md +++ b/analyses/0008-backstage/backstage-analysis.md @@ -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 diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md index dd3d0b5..aed5ff2 100644 --- a/analyses/0009-in-toto/in-toto-analysis.md +++ b/analyses/0009-in-toto/in-toto-analysis.md @@ -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** diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index b747401..fdc48cc 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -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..." diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 85bd9de..8bb1ccf 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -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 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..." diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md index 18824fe..6c3d20c 100644 --- a/analyses/0010-etcd/etcd-analysis.md +++ b/analyses/0010-etcd/etcd-analysis.md @@ -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. [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]: diff --git a/analyses/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md index a6e254c..bbce31c 100644 --- a/analyses/0010-etcd/etcd-implementation.md +++ b/analyses/0010-etcd/etcd-implementation.md @@ -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 diff --git a/analyses/0010-etcd/etcd-issues.md b/analyses/0010-etcd/etcd-issues.md index e1c6137..de88f65 100644 --- a/analyses/0010-etcd/etcd-issues.md +++ b/analyses/0010-etcd/etcd-issues.md @@ -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 diff --git a/analyses/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md index 2744b07..bf87976 100644 --- a/analyses/0011-keda/keda-analysis.md +++ b/analyses/0011-keda/keda-analysis.md @@ -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 | diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 552d69e..7508886 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -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 diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 512b9a4..2d3bb63 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -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 diff --git a/analyses/README.md b/analyses/README.md index 1ca657d..6126754 100644 --- a/analyses/README.md +++ b/analyses/README.md @@ -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 diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 613b8a8..b98f87b 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -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 diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index 70fa619..ff83ceb 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -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 diff --git a/docs/analysis/resources/README.md b/docs/analysis/templates/README.md similarity index 74% rename from docs/analysis/resources/README.md rename to docs/analysis/templates/README.md index d39d6fd..18aa6a6 100644 --- a/docs/analysis/resources/README.md +++ b/docs/analysis/templates/README.md @@ -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. diff --git a/docs/analysis/resources/analysis-template.md b/docs/analysis/templates/analysis.md similarity index 98% rename from docs/analysis/resources/analysis-template.md rename to docs/analysis/templates/analysis.md index 7108821..e82706b 100644 --- a/docs/analysis/resources/analysis-template.md +++ b/docs/analysis/templates/analysis.md @@ -542,14 +542,14 @@ We evaluate on the following: -[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 diff --git a/docs/analysis/resources/implementation-template.md b/docs/analysis/templates/implementation.md similarity index 100% rename from docs/analysis/resources/implementation-template.md rename to docs/analysis/templates/implementation.md diff --git a/docs/analysis/resources/issue-template.md b/docs/analysis/templates/issue.md similarity index 90% rename from docs/analysis/resources/issue-template.md rename to docs/analysis/templates/issue.md index e12af81..4dbcbba 100644 --- a/docs/analysis/resources/issue-template.md +++ b/docs/analysis/templates/issue.md @@ -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: 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` diff --git a/docs/analysis/resources/umbrella-issue-template.md b/docs/analysis/templates/umbrella-issue.md similarity index 82% rename from docs/analysis/resources/umbrella-issue-template.md rename to docs/analysis/templates/umbrella-issue.md index f834846..7e44352 100644 --- a/docs/analysis/resources/umbrella-issue-template.md +++ b/docs/analysis/templates/umbrella-issue.md @@ -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: 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: + # Issues @@ -28,7 +28,7 @@ website and technical documentation. -- [ ] https://github.com/project/repo/issues/NNN +- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` ## Issue: Item 2 diff --git a/package.json b/package.json index 92c7942..bb7ccc0 100644 --- a/package.json +++ b/package.json @@ -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",