cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[chore] Enable spell-check and fix spelling 

Signed-off-by: Patrice Chalin <pchalin@gmail.com>
This commit is contained in:
Patrice Chalin 2025-02-26 04:45:07 -05:00 committed by Patrice Chalin
parent ff86e0a055
commit 02e2c9e908
33 changed files with 184 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.cspell.yml
View File

@ -4,9 +4,8 @@
version: '0.2' version: '0.2'
caseSensitive: true caseSensitive: true
ignorePaths: ignorePaths:
# Temporary until https://github.com/cncf/techdocs/pull/229 is merged - '*.csv'
- /docs/ - /docs/localization/ja
- /assessments/
# patterns: # patterns:
# - name: CodeBlock # - name: CodeBlock
# pattern: | # pattern: |
@ -23,9 +22,13 @@ ignorePaths:
words: words:
- nvmrc - nvmrc
- backstore - backstore
- CLOTributor
- CNCF - CNCF
- Docsy - Docsy
- keda - keda
- kedacore - kedacore
- subpages
- techdocs - techdocs
- toolkits
- toto - toto
- triaging

12
analyses/0001-contour.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Horgan celestehorgan hashlinks
---
# Docs assessment # Docs assessment
## Introduction ## Introduction
@ -174,8 +178,8 @@ website, and in the repo. Great job team!
- Update - Update
[SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md) [SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md)
to Hugo when ready. to Hugo when ready.
- Do a backlog clean of `kind/docuentation` and ensure that all issues are still - Do a backlog clean of `kind/documentation` and ensure that all issues are
valid. Close any which are not. For example still valid. Close any which are not. For example
[this issue](https://github.com/projectcontour/contour/issues/2053) was opened [this issue](https://github.com/projectcontour/contour/issues/2053) was opened
in 2019. in 2019.
- Improve stub issue descriptions - Improve stub issue descriptions
@ -203,7 +207,7 @@ website, and in the repo. Great job team!
native community. While ideally we would see a logo wall of users or case native community. While ideally we would see a logo wall of users or case
studies, for a project of contour's size this is a great addition to the site. studies, for a project of contour's size this is a great addition to the site.
- **Maitenence planning**: - **Maintenance planning**:
- **Monorepos**: Having a docs+code monorepo is risky in the long term, as it - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it
couples all docs builds with code builds and vice versa. If docs CI fails couples all docs builds with code builds and vice versa. If docs CI fails
because Netlify is temporarily down, for example, this means that all your because Netlify is temporarily down, for example, this means that all your
@ -223,7 +227,7 @@ website, and in the repo. Great job team!
better to have padding above an h2 rather than below it, as this helps better to have padding above an h2 rather than below it, as this helps
separate each section of a page. separate each section of a page.
- **Maitenence planning**: Unless you have very good reasons for staying in a - **Maintenance planning**: Unless you have very good reasons for staying in a
docs+code monorepo, we strongly suggest migrating documentation to its own docs+code monorepo, we strongly suggest migrating documentation to its own
repository and maintaining it separately. repository and maintaining it separately.

8
analyses/0002-notary-project.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: docset notaryproject celestehorgan
---
# Notary Project Docs Assessment # 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/)
@ -223,8 +227,8 @@ developed?
_Note_: _Note_:
[Notary Project branding artwork](https://github.com/cncf/artwork/tree/master/projects/notary) [Notary Project branding artwork](https://github.com/cncf/artwork/tree/master/projects/notary)
exists. Other branding elements, like colour schemes and whatnot, will need to exists. Other branding elements, like color schemes and whatnot, will need to be
be developed. developed.
### Information Architecture ### Information Architecture

18
analyses/0003-krator.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Krator celestehorgan CODEOWNERS
---
# Krator Docs assessment # Krator Docs assessment
## Introduction ## Introduction
@ -53,9 +57,9 @@ Criteria:
- Documentation is currently in several locations and will need to be brought - Documentation is currently in several locations and will need to be brought
into one repo. The current resources are: into one repo. The current resources are:
- The project [README](https://github.com/krator-rs/krator) - The project [README](https://github.com/krator-rs/krator)
- [Introduction to krator Blog Post](https://deislabs.io/posts/introducing-krator/) - [Introduction to Krator Blog Post](https://deislabs.io/posts/introducing-krator/)
- [A Fistful of States: More State Machine Patterns in Rust](https://deislabs.io/posts/a-fistful-of-states/) - [A Fistful of States: More State Machine Patterns in Rust](https://deislabs.io/posts/a-fistful-of-states/)
- [Crate krator API Documentation](https://docs.rs/krator/0.4.0/krator/). - [Crate Krator API Documentation](https://docs.rs/krator/0.4.0/krator/).
This is a substantial part of the current documentation and could be This is a substantial part of the current documentation and could be
incorporated into the main body (site/repo) of the documentation. This is incorporated into the main body (site/repo) of the documentation. This is
already a great resource for users, but if we transport it to a already a great resource for users, but if we transport it to a
@ -83,7 +87,7 @@ Criteria:
- We'll need to create a clear entry point for the new user. Some of this info - We'll need to create a clear entry point for the new user. Some of this info
could be taken from the could be taken from the
[Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md) [Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md)
and includes prerequisite knowlege, configuration, and a brief step-by-step and includes prerequisite knowledge, configuration, and a brief step-by-step
guide on adding Krator to your project. guide on adding Krator to your project.
- **Content maintainability**: - **Content maintainability**:
- Since we'll be creating a site, search doesn't apply yet (though will be - Since we'll be creating a site, search doesn't apply yet (though will be
@ -117,19 +121,19 @@ Criteria:
creating a Getting Started/Quickstart. creating a Getting Started/Quickstart.
- **Tutorials** - **Tutorials**
- **Setting up Krator** - **Setting up Krator**
- **Configuring your project to use krator** - **Configuring your project to use Krator**
- **Tasks:** I recommend a section with step-by-step instructions on how to - **Tasks:** I recommend a section with step-by-step instructions on how to
accomplish the most common tasks in Krator. For example, if you have five accomplish the most common tasks in Krator. For example, if you have five
most common tasks, you could have a document for each. Suggestions include: most common tasks, you could have a document for each. Suggestions include:
- **Using built-in operators** - **Using built-in operators**
- **Creating your own operators with krator** - **Creating your own operators with Krator**
- Are there other common tasks? If so, they should go here. - Are there other common tasks? If so, they should go here.
- **Best practices** - **Best practices**
- **Troubleshooting** - **Troubleshooting**
- **Troubleshooting** - **Troubleshooting**
- **Error Reference** A table with explanations and resolution steps would - **Error Reference** A table with explanations and resolution steps would
suffice suffice
- **Contributing to krator** - **Contributing to Krator**
- **Cutting releases** (This is existing documentation) - **Cutting releases** (This is existing documentation)
- **Contributing:** Include information on submitting issues and - **Contributing:** Include information on submitting issues and
instructions with links on contributing to the code base and to the instructions with links on contributing to the code base and to the
@ -196,7 +200,7 @@ be done!
<!-- borrowed from @celestehorgan's excellent work in 0001-contour.md --> <!-- borrowed from @celestehorgan's excellent work in 0001-contour.md -->
- **Maitenence planning**: - **Maintenance planning**:
- **Monorepos**: Having a docs+code monorepo is risky in the long term, as it - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it
couples all docs builds with code builds and vice versa. If docs CI fails couples all docs builds with code builds and vice versa. If docs CI fails
because Netlify is temporarily down, for example, this means that all your because Netlify is temporarily down, for example, this means that all your

4
analyses/0004-tremor.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Horgan onramps offramps LLDB Wayfair
---
# Assessment: Project Tremor # Assessment: Project Tremor
Prepared by: Celeste Horgan Date: July 2021 Prepared by: Celeste Horgan Date: July 2021

4
analyses/0005-fluxcd.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: celestehorgan Horgan
---
# Assessment template # Assessment template
Prepared by: Celeste Horgan Prepared by: Celeste Horgan

6
analyses/0006-gateway-api.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes
---
# Assessment: Project Kubernetes Gateway API # Assessment: Project Kubernetes Gateway API
Prepared by: Meha Bhalodiya Prepared by: Meha Bhalodiya
@ -95,7 +99,7 @@ as well as where to find them.
- Reference - Reference
- Contribute - Contribute
- **Prepared a miro board: - **Prepared a Miro board:
[https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)** [https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)**
![information_architecture](../docs/images/gapi_info_arch.png) ![information_architecture](../docs/images/gapi_info_arch.png)

6
analyses/0007-porter.md
View File

@ -1,6 +1,6 @@
--- ---
title: Porter tech docs assessment draft title: Porter tech docs assessment draft
tags: porter cSpell:ignore: Uchechukwu Obasi
--- ---
# Notes # Notes
@ -103,7 +103,7 @@ Scale:
- Multiple OSes are well documented too. - Multiple OSes are well documented too.
- The onboarding and contributing guides are well documented making it easy for - The onboarding and contributing guides are well documented making it easy for
new users to understand and kickstart. new users to understand and kickstart.
- Porter's sample code is copy-pastable. - Porter's sample code can be copy-pasted.
- "What is Porter?" is a good overview or 'about' section. - "What is Porter?" is a good overview or 'about' section.
- Items listed under "When to use Porter?" are inconsistent with the way they're - Items listed under "When to use Porter?" are inconsistent with the way they're
linked: some are linked while others are not. linked: some are linked while others are not.
@ -140,7 +140,7 @@ Scale:
- Overall, Porter's documentation is well organized: - Overall, Porter's documentation is well organized:
- some pages seem misplaced (quick start for operator, ...) - some pages seem misplaced (quick start for operator, ...)
- Some pages appear at the top level of the docs nav that may not need to be - Some pages appear at the top level of the docs nav that may not need to be
there -- search may help with findability there -- search may help with discoverability
- Best practices could be under reference - Best practices could be under reference
- Mixins Plugins -- should these be top level? - Mixins Plugins -- should these be top level?

2
analyses/0008-backstage/user-roles.md
View File

@ -6,7 +6,7 @@ around which to organize the Backstage documentation.
The documentation should ultimately be task-oriented, with tasks organized The documentation should ultimately be task-oriented, with tasks organized
around users and their objectives. A process for creating this type of around users and their objectives. A process for creating this type of
documentation set is under development in the CDCF Tech Doc GitHub project. documentation set is under development in the CNCF Tech Doc GitHub project.
## Summary of Proposed User Roles ## Summary of Proposed User Roles

2
analyses/0009-in-toto/in-toto-analysis.md
View File

@ -176,7 +176,7 @@ in the Get Started menu (wherever that ends up).
Almost all doc content is in GitHub (in README files, the Specification, or Almost all doc content is in GitHub (in README files, the Specification, or
comments in demos). Most of it should be exposed as indexed documents on the comments in demos). Most of it should be exposed as indexed documents on the
website to make it versionable, editable, and localizable. website so it can be edited, versioned, and localized.
- Move most of the documentation into read-the-docs (RTD) so that it can - Move most of the documentation into read-the-docs (RTD) so that it can
properly indexed and maintained. properly indexed and maintained.

4
analyses/0009-in-toto/in-toto-doc-issues.md
View File

@ -102,9 +102,9 @@ This should be fixed or removed.)
that describes the ITE process, which is two levels down from main in the that describes the ITE process, which is two levels down from main in the
[ITE repo](https://github.com/in-toto/ITE/). The document should be [ITE repo](https://github.com/in-toto/ITE/). The document should be
referenced in the section for Contributors, and possibly a subsection referenced in the section for Contributors, and possibly a subsection
sepecifically intended for ITE proposers and developers. specifically intended for ITE proposers and developers.
- [ ] As documents are transfered from GitHub into the Doc web site, update the - [ ] As documents are transferred from GitHub into the Doc web site, update the
index accordingly and adjust the doc architecture as needed. index accordingly and adjust the doc architecture as needed.
## Establish policy for reference material ## Establish policy for reference material

14
analyses/0009-in-toto/in-toto-implementation.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: roadmaps Cappos
---
# Implementation # Implementation
## Organizational principles ## Organizational principles
@ -54,10 +58,10 @@ Users with the following roles are potential audiences for in-toto project
documentation. documentation.
| User Role | Doc needs | | User Role | Doc needs |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Evaluators** determine whether in-toto meets their needs and can be implemented in their organization. | High-level technical overview with a marketing slant, analysis of business benefits, adoption and success stories, and a workflow overview. | | **Evaluators** determine whether in-toto meets their needs and can be implemented in their organization. | High-level technical overview with a marketing slant, analysis of business benefits, adoption and success stories, and a workflow overview. |
| **End users** can be _Project owners_ and _Functionaries_. | End users can be new or experienced. New users need a clear learning path and general examples. Experienced users need reference docs and use-case examples. | | **End users** can be _Project owners_ and _Functionaries_. | End users can be new or experienced. New users need a clear learning path and general examples. Experienced users need reference docs and use-case examples. |
| **Project owners** define the layout to be followed when, e.g., using the in-toto CLI tools. When doing so, they specify who is intended to sign for every piece of link metadata, any sublayouts that may exist, and how to further verify accompanying metadata. | New users need an overview, demos, templates, and basic instructions. Experienced users need deeper architectural info, use cases, and examples. | | **Project owners** define the layout to be followed when, e.g., using the in-toto CLI tools. When doing so, they specify who is intended to sign for every piece of link metadata, any sub-layouts that may exist, and how to further verify accompanying metadata. | New users need an overview, demos, templates, and basic instructions. Experienced users need deeper architectural info, use cases, and examples. |
| **Functionaries** perform the intended actions and produce link metadata for each step. | _?? do these users read in-toto doc at all, or is the project owner responsible for instructing them in how to sign and verify their steps??_ | | **Functionaries** perform the intended actions and produce link metadata for each step. | _?? do these users read in-toto doc at all, or is the project owner responsible for instructing them in how to sign and verify their steps??_ |
| **Contributors** can be contributors to the _code_ base and to the _documentation_ of the OSS project itself. | Contributors need project standards and instructions, community guidelines, and GitHub instructions specific to the project. This information is often in the repo, and not in the project or product documentation. | | **Contributors** can be contributors to the _code_ base and to the _documentation_ of the OSS project itself. | Contributors need project standards and instructions, community guidelines, and GitHub instructions specific to the project. This information is often in the repo, and not in the project or product documentation. |
| **Code contributors** are members of the community who: _make code changes_, _submit changes to specifications_, _create new integrations_, and _submit issues, feature requests and more_ | These contributors need to understand the GitHub repo structure, the contribution policies and procedures, coding and naming standards and conventions. ITE developers and integrators need direction on how and where to document their own additions. | | **Code contributors** are members of the community who: _make code changes_, _submit changes to specifications_, _create new integrations_, and _submit issues, feature requests and more_ | These contributors need to understand the GitHub repo structure, the contribution policies and procedures, coding and naming standards and conventions. ITE developers and integrators need direction on how and where to document their own additions. |
@ -210,10 +214,10 @@ following general plan.
describes the ITE process, which is two levels down from main in the describes the ITE process, which is two levels down from main in the
[ITE repo](https://github.com/in-toto/ITE/). The document should be [ITE repo](https://github.com/in-toto/ITE/). The document should be
referenced in the section for Contributors, and possibly a subsection referenced in the section for Contributors, and possibly a subsection
sepecifically intended for ITE proposers and developers. specifically intended for ITE proposers and developers.
4.4 As documents are transfered from GitHub into the Doc web site, update the 4.4 As documents are transferred from GitHub into the Doc web site, update
index accordingly and adjust the doc architecture as needed. the index accordingly and adjust the doc architecture as needed.
5. Reference material 5. Reference material

18
analyses/0010-etcd/etcd-analysis.md
View File

@ -4,6 +4,7 @@ tags: etcd
created: 2023-09-01 created: 2023-09-01
modified: 2024-01-08 modified: 2024-01-08
author: Dave Welsch (@dwelsch-esi) author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch
--- ---
# Introduction # Introduction
@ -23,14 +24,14 @@ efforts.
This document was written to analyze the current state of etcd documentation. It This document was written to analyze the current state of etcd documentation. It
aims to provide project leaders with an informed understanding of potential aims to provide project leaders with an informed understanding of potential
problems in current project documentation. The companion document, problems in current project documentation. The companion document,
etcd-impementation.md, outlines an actionable plan for improvement. etcd-implementation.md, outlines an actionable plan for improvement.
This document: This document:
- Analyzes the current etcd technical documentation and website - Analyzes the current etcd technical documentation and website
- Compares existing documentation against the CNCF’s standards - Compares existing documentation against the CNCF’s standards
- Recommends a program of key improvements with the largest return on - Recommends a program of key improvements with the largest return on
investment. The companion document, etcd-impementation.md, provides specific investment. The companion document, etcd-implementation.md, provides specific
actionable suggestions and recommendations for overall organization and actionable suggestions and recommendations for overall organization and
presentation of documentation presentation of documentation
@ -94,7 +95,7 @@ to their area of concern:
- [Project documentation][proj-doc] - [Project documentation][proj-doc]
- [Contributor documentation][contributor-doc] - [Contributor documentation][contributor-doc]
- [Website and documentation infrrastructure][website] - [Website and documentation infrastructure][website]
Examples of CNCF documentation that demonstrate the analysis criteria are linked Examples of CNCF documentation that demonstrate the analysis criteria are linked
from the [Criteria][cncf-doc-criteria] specification. from the [Criteria][cncf-doc-criteria] specification.
@ -331,9 +332,9 @@ Reorganize the table of contents (ToC) to separate three types of information:
material by user role: for etcd, the two main user roles seem to be 1) material by user role: for etcd, the two main user roles seem to be 1)
developers, and 2) operators or admins responsible for running and maintaining developers, and 2) operators or admins responsible for running and maintaining
etcd server instances. etcd server instances.
- **Reference**: The details of CLI commands, API metehods and objects, system - **Reference**: The details of CLI commands, API methods and objects, system
configuration options, and other information that needs to be looked up in the configuration options, and other information that needs to be looked up in the
course of performning a task. course of performing a task.
For an excellent and very literal example of this approach, see the [Kubernetes For an excellent and very literal example of this approach, see the [Kubernetes
documentation][k8s-doc]. documentation][k8s-doc].
@ -507,7 +508,7 @@ minimal difficulty **finding help** if they need it.
### Project governance documentation ### Project governance documentation
[**Project goverance**][etcd-govern] is clearly documented. [**Project governance**][etcd-govern] is clearly documented.
## Recommendations ## Recommendations
@ -527,7 +528,7 @@ repo, with links to the other contributor resources.
### Project governance documentation ### Project governance documentation
No recommnendations. No recommendations.
# Website # Website
@ -682,8 +683,7 @@ documentation for all major use cases for each stakeholder.
### Usability, accessibility and devices ### Usability, accessibility and devices
Consider replaciing low-contrast text for the benefit of visually impaired Consider replacing low-contrast text for the benefit of visually impaired users.
users.
### Branding and design ### Branding and design

6
analyses/0010-etcd/etcd-implementation.md
View File

@ -6,7 +6,7 @@ tags: etcd
# Introduction # Introduction
This document provides actionable suggestions for improving the etcd technical This document provides actionable suggestions for improving the etcd technical
documentaiton. documentation.
For an analysis and general discussion of recommendations on etcd technical For an analysis and general discussion of recommendations on etcd technical
documentation, see [etcd-analysis.md][etcd-analysis]. documentation, see [etcd-analysis.md][etcd-analysis].
@ -266,8 +266,8 @@ section.
**_Disaster recovery_**: Consolidate with other troubleshooting procedures. **_Disaster recovery_**: Consolidate with other troubleshooting procedures.
**_Hardware recommendations_**: System prerequisite. Move to somewhere before **_Hardware recommendations_**: System prerequisite. Move to somewhere before
the Cluster Installation section; maybe even put it in a Prereq heading in that the Cluster Installation section; maybe even put it in a prerequisite heading in
section. that section.
**_Maintenance_**: Maybe provide a more specific title like "Storage **_Maintenance_**: Maybe provide a more specific title like "Storage
maintenance". maintenance".

10
analyses/0010-etcd/etcd-issues.md
View File

@ -1,6 +1,6 @@
--- ---
title: etcd Umbrella Issue title: etcd Umbrella Issue
tags: etcd cSpell:ignore: reconf
--- ---
# Overview # Overview
@ -334,13 +334,13 @@ section is probably easier.
Longer explanations in the FAQ might be better as part of conceptual information Longer explanations in the FAQ might be better as part of conceptual information
-- for example, in the system or architecture overview. Retain the short answers -- for example, in the system or architecture overview. Retain the short answers
that don't fit elesewhere. that don't fit elsewhere.
## Issue: Create a System Overview ## Issue: Create a System Overview
Rename the "Learning" section to "System Overview" or "Conceptual Overview". Rename the "Learning" section to "System Overview" or "Conceptual Overview".
This is the place for detailed explanations of the system philosophy, design, This is the place for detailed explanations of the system philosophy, design,
and architeture. Edit the content, limiting it to explaining concepts. Move and architecture. Edit the content, limiting it to explaining concepts. Move
instructional and reference topics to their own areas of the documentation. instructional and reference topics to their own areas of the documentation.
Move the section to earlier in ToC, perhaps before "Installation". Move the section to earlier in ToC, perhaps before "Installation".
@ -353,8 +353,8 @@ Include in architecture overview.
### etcd client design ### etcd client design
Include in architecture overview. Remove the Glossary and merge it into the Include in architecture overview. Remove the Glossary and merge it into the site
sitewide Glossary. wide Glossary.
### etcd learner design ### etcd learner design

4
analyses/0012-TUF/README.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: theupdateframework
---
# TUF Documentation Analysis # TUF Documentation Analysis
This section contains analysis of The Update Framework (TUF) project This section contains analysis of The Update Framework (TUF) project

15
analyses/0012-TUF/analysis.md
View File

@ -4,9 +4,10 @@ tags: TUF
created: 2024-06-17 created: 2024-06-17
modified: YYYY-MM-DD modified: YYYY-MM-DD
author: Sandra Dindi (@Dindihub) author: Sandra Dindi (@Dindihub)
cSpell:ignore: Dindi Dindihub RSTUF theupdateframework
--- ---
<!-- markdownlint-disable no-duplicate-heading no-empty-links --> <!-- markdownlint-disable no-duplicate-heading -->
## Introduction ## Introduction
@ -109,7 +110,7 @@ to their area of concern:
- [Contributor documentation](#contributor-documentation) - [Contributor documentation](#contributor-documentation)
- [Website and infastructure](#website-and-infrastructure) - [Website and infrastructure](#website-and-infrastructure)
#### Recommendations, requirements, and best practices #### Recommendations, requirements, and best practices
@ -168,7 +169,7 @@ Scale:
- Repetition of content on different pages makes content confusing - Repetition of content on different pages makes content confusing
- Re-organise content to make it easier to follow - Re-organize content to make it easier to follow
- There are no tutorials for specific feature implementation. But, there are - There are no tutorials for specific feature implementation. But, there are
videos explaining various use cases. videos explaining various use cases.
@ -214,7 +215,7 @@ Scale:
#### Content maintainability & site mechanics #### Content maintainability & site mechanics
- The documentation is not searchable. You have to go through the site to find - The documentation is not searchable. You have to go through the site to find
what you are looking for. The only source of naviagation is the menu bar. what you are looking for. The only source of navigation is the menu bar.
- The Docs are managed through docs-as-code site Hugo and content written in - The Docs are managed through docs-as-code site Hugo and content written in
markdown. However,it appears the updates are made manually. markdown. However,it appears the updates are made manually.
@ -242,7 +243,7 @@ Scale:
_Aborted_ is used in the _Aborted_ is used in the
[Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time)
- There is no use of abliest language like simple, or easy in the documentation. - There is no use of ableist language like simple, or easy in the documentation.
### Project recommendations ### Project recommendations
@ -453,7 +454,7 @@ the website repo.
- Information about the website build, tools and how to generate it are not - Information about the website build, tools and how to generate it are not
available on the website or the docs repo. available on the website or the docs repo.
- Intra-site search mechanism is not available from the website. The only - Intra-site search mechanism is not available from the website. The only
naviagation option is a menu bar. This makes it difficult to find information. navigation option is a menu bar. This makes it difficult to find information.
- A lot of empty space between the Hero section and the Navbar. Due to this - A lot of empty space between the Hero section and the Navbar. Due to this
spacing, information is pushed out of eye level. You have to scroll down to spacing, information is pushed out of eye level. You have to scroll down to
find it. find it.
@ -477,7 +478,7 @@ The website docs analysis is in progress.
#### Branding and design #### Branding and design
- There's a recognizable brand for the project , a logo and blue-white color - There's a recognizable brand for the project , a logo and blue-white color
scheme used througout the website. scheme used throughout the website.
- The website design is good and suitable for reading. However, consider - The website design is good and suitable for reading. However, consider
reducing the space between the hero section and the Navbar. reducing the space between the hero section and the Navbar.

10
analyses/0012-TUF/implementation.md
View File

@ -1,12 +1,12 @@
--- ---
title: Implementing TUF Doc Improvements title: Implementing TUF Doc Improvements
tags: TUF cSpell:ignore: RSTUF
--- ---
## Introduction ## Introduction
This document provides actionable suggestions for improving the This document provides actionable suggestions for improving the **The Update
**theUpdateframework (TUF)** technical documentation. Framework (TUF)** technical documentation.
For an analysis and general discussion of recommendations on TUF technical For an analysis and general discussion of recommendations on TUF technical
documentation, see [analysis](./analysis.md). documentation, see [analysis](./analysis.md).
@ -157,7 +157,7 @@ it easier for contributors to contact them.
### Add labels to the website repo ### Add labels to the website repo
Include labels to issues in the website repo. These include labels such as Include labels to issues in the website repo. These include labels such as
_#docs \#Goodfirstissue_ to make it easier for contributors to get started. `docs` and `good first issue` to make it easier for contributors to get started.
### Develop a guidelines for new users and contributors ### Develop a guidelines for new users and contributors
@ -176,7 +176,7 @@ some good suggestions.
Provide information about project meetings and a calendar on both the website Provide information about project meetings and a calendar on both the website
and repo. Makes it easier for contributors to sync with their calendars and get and repo. Makes it easier for contributors to sync with their calendars and get
notifications about meetings. I like how the notifications about meetings. I like how the
[**Meshery**](https://github.com/layer5io/layer5) project has implemented this. [Layer 5](https://github.com/layer5io/layer5) project has implemented this.
## Proposed Information Architecture for the TUF Website ## Proposed Information Architecture for the TUF Website

18
analyses/0012-TUF/issues.md
View File

@ -1,6 +1,6 @@
--- ---
title: TUF Issue title: TUF Issue
tags: TUF cSpell:ignore: theupdateframework
--- ---
## Overview ## Overview
@ -16,10 +16,10 @@ analysis and implementation plan.
### Reorganize website content ### Reorganize website content
Reorganize website content by introducing new sections and consolidating some Reorganize website content by introducing new sections and consolidating some
pages. For example, a docs section can accomodate most pages on the website. pages. For example, a docs section can accommodate most pages on the website.
View the proposed outline in the [Implementation document](./implementation.md) View the proposed outline in the [Implementation document](./implementation.md)
This proposed change consolidates related pages and removes others, chnaging the This proposed change consolidates related pages and removes others, changing the
structure of the current website structure of the current website
[theupdateframework.io](https://theupdateframework.io/) [theupdateframework.io](https://theupdateframework.io/)
@ -36,7 +36,7 @@ These can be further broken down into subsections depending on use case:
- Adopters : - Adopters :
- Client maintainers - Client maintainers
- Respository maintainers - Repository maintainers
- Contributors: - Contributors:
- Spec contributors - Spec contributors
- Docs contributors - Docs contributors
@ -49,7 +49,7 @@ repository for doc contributors.
Audience: Admin Audience: Admin
Type: Conseptual Type: Conceptual
### Add introductory Video to homepage ### Add introductory Video to homepage
@ -58,7 +58,7 @@ Type: Conseptual
Audience: Admin Audience: Admin
Type: Conseptual Type: Conceptual
### Add a 'Schedule and appointment' icon to the website ### Add a 'Schedule and appointment' icon to the website
@ -67,7 +67,7 @@ Type: Conseptual
Audience: Admin Audience: Admin
Type: Conseptual Type: Conceptual
### Introduce Instructional material for user roles ### Introduce Instructional material for user roles
@ -115,8 +115,8 @@ Type: Conceptual
### Add labels to the website repo ### Add labels to the website repo
Add labels to issues in the website repo to make it easier for contributors to Add labels to issues in the website repo to make it easier for contributors to
identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier identify suitable issues. Labels such as `docs` and `good first issue` make it
for contributors to get started. easier for contributors to get started.
Audience: Admin Audience: Admin

5
analyses/0013-litmuschaos/litmuschaos-analysis.md
View File

@ -4,7 +4,8 @@ tags: LitmusChaos
created: 2024-08-02 created: 2024-08-02
modified: 2024-10-09 modified: 2024-10-09
author: Dave Welsch (@dwelsch-esi) author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Docusaurus rfc OSes pastable impl servicedesk md # prettier-ignore
cSpell:ignore: Welsch dwelsch litmusctl embedmd litmuschaos mkdocs subsite codelab
--- ---
<!-- markdownlint-disable no-duplicate-heading --> <!-- markdownlint-disable no-duplicate-heading -->
@ -308,7 +309,7 @@ respectively. Explain the usage scenario at the top of each procedure.
Rather than duplicating information in different scenarios (basic vs. advanced Rather than duplicating information in different scenarios (basic vs. advanced
install, for example), write single sub-procedures and link to them from the install, for example), write single sub-procedures and link to them from the
main procedure or include them as prereqs. main procedure or include them as prerequisites.
Explicitly call out the operating system for every install procedure. Explicitly call out the operating system for every install procedure.

7
analyses/0013-litmuschaos/litmuschaos-implementation.md
View File

@ -3,6 +3,7 @@ title: Implementing LitmusChaos Doc Improvements
tags: LitmusChaos tags: LitmusChaos
created: 2024-10-24 created: 2024-10-24
author: Dave Welsch (@dwelsch-esi) author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch
--- ---
<!-- markdownlint-disable no-duplicate-heading --> <!-- markdownlint-disable no-duplicate-heading -->
@ -152,7 +153,7 @@ be its own page.
[Harness](https://app.harness.io/auth/#/signin). [Harness](https://app.harness.io/auth/#/signin).
- **Local** (self-hosted): Use _Helm_ or `kubectl` - **Local** (self-hosted): Use _Helm_ or `kubectl`
- **Helm**: One-page install procedure. - **Helm**: One-page install procedure.
- **kubectl** (with a YAML spec file) Prereq: install MongoDB - **kubectl** (with a YAML spec file) Prerequisite: install MongoDB
- **Basic installation**: One-page install procedure. - **Basic installation**: One-page install procedure.
- **Advanced installation**: One-page install procedure. - **Advanced installation**: One-page install procedure.
- **Verify your installation**: One-page procedure. Next steps: Access the - **Verify your installation**: One-page procedure. Next steps: Access the
@ -186,9 +187,9 @@ detail here. Some guidelines for writing procedures:
chaos experiment" rather than "Schedule a chaos experiment". chaos experiment" rather than "Schedule a chaos experiment".
- Rather than duplicating information in different scenarios (basic vs. advanced - Rather than duplicating information in different scenarios (basic vs. advanced
install, for example), write single sub-procedures and link to them from the install, for example), write single sub-procedures and link to them from the
main procedure or include them as prereqs. main procedure or include them as prerequisites.
- Explicitly state which operating systems and platform the installation is for. - Explicitly state which operating systems and platform the installation is for.
This can be done in the Prereqs section. This can be done in the Prerequisites section.
- In all cases, use consistent naming for the sections as an aid to navigation. - In all cases, use consistent naming for the sections as an aid to navigation.
For example, the current documentation uses "Prerequisites" and "Before you For example, the current documentation uses "Prerequisites" and "Before you
begin" for the same information. begin" for the same information.

16
analyses/0013-litmuschaos/litmuschaos-issues.md
View File

@ -1,6 +1,6 @@
--- ---
title: Litmus Chaos Issue title: Litmus Chaos Issue
tags: Litmus Chaos cSpell:ignore: litmuschaos ChaoCenter
--- ---
<!-- markdownlint-disable line-length no-duplicate-heading no-emphasis-as-heading --> <!-- markdownlint-disable line-length no-duplicate-heading no-emphasis-as-heading -->
@ -207,7 +207,7 @@ There are several ways to do this:
assumes that making the user click to a common piece of information is a assumes that making the user click to a common piece of information is a
lesser liability than trying to maintain the same information in two (or more) lesser liability than trying to maintain the same information in two (or more)
places. It usually is. places. It usually is.
- Put the dupilcate information on its own page and include in-line everywhere - Put the duplicate information on its own page and include in-line everywhere
it's required (not easy to do here, since Markdown doesn't have a mechanism it's required (not easy to do here, since Markdown doesn't have a mechanism
for that like the Restructured Text ".. include" directive.) for that like the Restructured Text ".. include" directive.)
@ -327,7 +327,7 @@ same sections as shown for the User Guides in the TOC:
- Environments - Environments
- Chaos Infrastructure - Chaos Infrastructure
- Injecting Fault - Injecting Fault
- Resilience Probjes - Resilience Probes
- Account Settings - Account Settings
- User Management - User Management
- Managing Projects - Managing Projects
@ -349,7 +349,7 @@ sections as shown for Concepts in the TOC:
- GitOps - GitOps
- Authentication in ChaosCenter - Authentication in ChaosCenter
Also, make sure the TOC entries have consistent captitalization and agree with Also, make sure the TOC entries have consistent capitalization and agree with
the Overview headings. For example, "Chaos experiment" is sentence-style the Overview headings. For example, "Chaos experiment" is sentence-style
capitalization; "Chaos Experiment" is title capitalization. Pick one or the capitalization; "Chaos Experiment" is title capitalization. Pick one or the
other for the site. Don't mix and match. other for the site. Don't mix and match.
@ -491,12 +491,12 @@ here. Some guidelines for writing procedures:
tell the reader what to do ("Save and run the experiment. You are redirected tell the reader what to do ("Save and run the experiment. You are redirected
to the experiment execution page where the experiment execution steps are to the experiment execution page where the experiment execution steps are
visualized"). visualized").
- Use gerunds ("-ing" verbs) to title proceure pages; for example "Scheduling a - Use gerunds ("-ing" verbs) to title procedure pages; for example "Scheduling a
chaos experiment" rather than "Schedule a chaos experiment". chaos experiment" rather than "Schedule a chaos experiment".
- Explicitly state which operating systems and platform the installation is for. - Explicitly state which operating systems and platform the installation is for.
This can be done in the Prereqs section. This can be done in the Prerequisites section.
- In all cases, use conistent naming for the sections as an aid to navigation. - In all cases, use consistent naming for the sections as an aid to navigation.
For example, the current documentation uses "Prerequisites" and "Before you For example, the current documentation uses "Prerequisites" and "Before you
begin" for the same information. begin" for the same information.
- Similarly, retitle "Learn More" as "Next Steps", and write explanations for - Similarly, retitle "Learn More" as "Next Steps", and write explanations for
@ -575,7 +575,7 @@ the relevant portion.
### Overview ### Overview
There are several good articles in the Litmus Chaos blog that expand and explain There are several good articles in the Litmus Chaos blog that expand and explain
Litmus funtionality. Blog posts that run through an end-to-end example would Litmus functionality. Blog posts that run through an end-to-end example would
make good tutorials. If any posts explain core functional capabilities, they make good tutorials. If any posts explain core functional capabilities, they
should be included in the Litmus technical documentation so they are findable by should be included in the Litmus technical documentation so they are findable by
users. users.

5
docs/analysis/criteria.md
View File

@ -37,10 +37,7 @@ specifically for them. We evaluate on the following:
- Do users know where to go after reading the getting started guide? - Do users know where to go after reading the getting started guide?
- Is your new user content clearly signposted on your site’s homepage or at the - Is your new user content clearly signposted on your site’s homepage or at the
top of your information architecture? top of your information architecture?
- Is there easily copy-pastable sample code or other example content? - Is there sample code or other example content that can easily be copy-pasted?
<!-- markdownlint-enable line-length -->
<!-- cSpell:ignore OSes copy-pastable Algolia Docsy -->
Example: Example:

2
docs/analysis/howto.md
View File

@ -62,7 +62,7 @@ for
next index available in the directory (check for PRs as well, if someone else next index available in the directory (check for PRs as well, if someone else
is working on tech doc analyses), and where _PROJECT_ is a short but not is working on tech doc analyses), and where _PROJECT_ is a short but not
abbreviated project name. For example, for Kubernetes _PROJECT_ would be abbreviated project name. For example, for Kubernetes _PROJECT_ would be
_kubernetes_, not _k8s_. _Kubernetes_, not _k8s_.
4. Copy all the doc analysis [templates]. 4. Copy all the doc analysis [templates].
### Writing the Analysis document ### Writing the Analysis document

15
docs/analysis/templates/analysis.md
View File

@ -44,10 +44,11 @@ efforts.
This document was written to analyze the current state of _PROJECT_ This document was written to analyze the current state of _PROJECT_
documentation. It aims to provide project leaders with an informed understanding documentation. It aims to provide project leaders with an informed understanding
of potential problems in current project documentation. A second [impementation] of potential problems in current project documentation. A second
document, , outlines an actionable plan for improvement. A third document is an [implementation] document, , outlines an actionable plan for improvement. A
[issues list] of issues to be added to the project documentation repository. third document is an [issues list] of issues to be added to the project
These issues can be taken up by contributors to improve the documentation. documentation repository. These issues can be taken up by contributors to
improve the documentation.
This document: This document:
@ -62,7 +63,7 @@ the technical documentation, and documentation for contributors and users on the
_PROJECT_ GitHub repository. _PROJECT_ GitHub repository.
The _PROJECT_ website and documentation are written in [Markdown, ReStructured The _PROJECT_ website and documentation are written in [Markdown, ReStructured
Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static Text, other] and are compiled using the [Hugo, Docusaurus, Sphinx, other] static
site generator with the [Docsy, other] theme and served from [the Netlify site generator with the [Docsy, other] theme and served from [the Netlify
platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. platform, other]. The site's code is stored on the _PROJECT_ GitHub repo.
@ -196,7 +197,7 @@ specifically for them. We evaluate on the following:
- Do users know where to go after reading the getting started guide? - Do users know where to go after reading the getting started guide?
- Is your new user content clearly signposted on your site’s homepage or at the - Is your new user content clearly signposted on your site’s homepage or at the
top of your information architecture? top of your information architecture?
- Is there easily copy-pastable sample code or other example content? - Is there sample code or other example content that can easily be copy-pasted?
#### Content maintainability & site mechanics #### Content maintainability & site mechanics
@ -381,7 +382,7 @@ and documentation infrastructure rubric.
> these criteria. Keep in mind that much of the website infrastructure criteria > these criteria. Keep in mind that much of the website infrastructure criteria
> depend on the tools (static site generator, website framework and hosting, > depend on the tools (static site generator, website framework and hosting,
> analytics tools, etc.) and processes (project CI, release procedures, > analytics tools, etc.) and processes (project CI, release procedures,
> goverance, etc.) used to produce the documentation. (Criteria are copied from > governance, etc.) used to produce the documentation. (Criteria are copied from
> criteria.md) > criteria.md)
#### Single-source requirement #### Single-source requirement

4
docs/analytics.md
View File

@ -1,4 +1,6 @@
<!-- cSpell:ignore chalin gtag opentelemetry --> ---
cSpell:ignore: gtag kubernetes
---
# Analytics # Analytics

18
docs/netlify-domains-setup.md
View File

@ -1,21 +1,25 @@
---
cSpell:ignore: caniszczyk
---
# Netlify and domain setup # Netlify and domain setup
## Netlify ## Netlify
If a project already has its own Netlify instance, ask them to add If a project already has its own Netlify instance, ask them to add
@celestehorgan and @caniszczyk as administrators. As a part of their project [@caniszczyk][] as administrator. As a part of project onboarding, any billing
onboarding, any billing information should be taken care of. If it isn't, ask information should be taken care of. If it isn't, ask them to open a
them to open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket.
If a project does not have a website, or is migrating from using GitHub pages to If a project does not have a website, or is migrating from using GitHub pages to
Netlify, create a new site for them under the CNCF Projects netlify instance. Netlify, create a new site for them under the CNCF Projects netlify instance.
### Netlify maintainers ### Netlify maintainers
- Ensure that @celestehorgan and @caniszczyk are Owners if they are not already. - Ensure that [@caniszczyk][] is an Owner.
- Contact the project and ask for **at least two** maintainers for Netlify. You - Contact the project and ask for **at least two** maintainers for Netlify. You
will need their GitHub usernames. Add them either as Collaborators to specific will need their GitHub usernames. Add them either as Collaborators to specific
sites (if in the CNCF Projects Netlify team) or as Collaboators for the sites (if in the CNCF Projects Netlify team) or as Collaborators for the
Netlify team. Netlify team.
## Domains ## Domains
@ -30,7 +34,7 @@ one.
In most cases, we prefer to manage domains for project websites using Netlify In most cases, we prefer to manage domains for project websites using Netlify
DNS. DNS.
At the moment, @caniszczyk manages domain transfers. At the moment, [@caniszczyk][] manages domain transfers.
### Netlify DNS domains ### Netlify DNS domains
@ -52,3 +56,5 @@ Occasionally projects have domain names that don't point to websites. These are
used for, among other things, email addresses. used for, among other things, email addresses.
Issues related to these should be forwarded on to Linux Foundation IT staff. Issues related to these should be forwarded on to Linux Foundation IT staff.
[@caniszczyk]: https://github.com/caniszczyk

6
docs/repo-setup.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore cncf
---
# Repository setup # Repository setup
We recommend that CNCF projects separate docs into their own repository, away We recommend that CNCF projects separate docs into their own repository, away
@ -40,7 +44,7 @@ For documentation this means you must:
[CC-BY-4.0 license](./LICENSE-docs). [CC-BY-4.0 license](./LICENSE-docs).
``` ```
2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the 2. Add both the CC-BY-4.0 `LICENSE-docs` and Apache 2.0 `LICENSE` files to the
root directory of the documentation. For a plain text versions of both, see root directory of the documentation. For a plain text versions of both, see
[cncf/project-template](https://github.com/cncf/project-template) [cncf/project-template](https://github.com/cncf/project-template)

8
docs/searching-documentation.md
View File

@ -5,7 +5,7 @@
This page describes some common alternatives for static site search. This page describes some common alternatives for static site search.
- [Google search](#programmable-search-engine-by-google) - [Google search](#programmable-search-engine-by-google)
- [Docsearch by Algolia](#docsearch-by-algolia) - [DocSearch by Algolia](#docsearch-by-algolia)
- [Lunr](#lunr) - [Lunr](#lunr)
## Programmable Search Engine by Google ## Programmable Search Engine by Google
@ -26,7 +26,7 @@ website.
- Search index is completely managed and hosted on Google servers. - Search index is completely managed and hosted on Google servers.
## Docsearch by Algolia ## DocSearch by Algolia
[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the [DocSearch](https://docsearch.algolia.com/) is a search tool powered by the
Algolia search engine that crawls your docs and provides a dropdown search Algolia search engine that crawls your docs and provides a dropdown search
@ -61,8 +61,8 @@ needing external, server-side, search services.
### Cons ### Cons
- Can be complex to configure and setup (If a team is already using hugo/docsy, - Can be complex to configure and setup (If a team is already using Hugo or
this should be _very_ easy to setup). Docsy, this should be _very_ easy to setup).
- Depending on site setup, may require javascript knowledge - Depending on site setup, may require javascript knowledge
## When Is It Best To Use One Over Another? ## When Is It Best To Use One Over Another?

2
docs/services.md
View File

@ -111,5 +111,5 @@ for an embedded writer.
formal request. Bear in mind that this project proposal will convert to the formal request. Bear in mind that this project proposal will convert to the
statement of work for a contractor and plan accordingly. statement of work for a contractor and plan accordingly.
> Note: Longer techncial writer engagements are subject to team availability and > Note: Longer technical writer engagements are subject to team availability and
> CNCF priorities. Availability is not guaranteed. > CNCF priorities. Availability is not guaranteed.

33
docs/versioning-documentation.md
View File

@ -1,6 +1,9 @@
# Technical Documentation Versioning with Hugo & Netlify ---
# prettier-ignore
cSpell:ignore Batard Brubaker Pursley velero fullversion githubbranch docsbranch Tanzu Rosland Horgan Takahashi
---
<!-- markdownlint-disable no-emphasis-as-heading --> # Technical Documentation Versioning with Hugo & Netlify
Technical Documents Versioning is an intersection of: Technical Documents Versioning is an intersection of:
@ -20,45 +23,41 @@ Things discussed in this article:
What are the main concerns when versioning technical documentation in a website? What are the main concerns when versioning technical documentation in a website?
**Readers** ### Readers
- Ease of navigation/understanding - Ease of navigation/understanding
**Maintainers / Writers** ### Maintainers / Writers
- How hard is it to update when it's time to cut a new version? - How hard is it to update when it's time to cut a new version?
**Necessity** ### Necessity
- Does the documentation need versioning yet? - Does the documentation need versioning yet?
- YAGNI (You aren't gonna need it - Don't implement things before you actually - YAGNI (You aren't gonna need it - Don't implement things before you actually
need them) need them)
**Navigation** ### Navigation
- Differences between versions (how do you deal with pages that have been added, - Differences between versions (how do you deal with pages that have been added,
removed, or moved between releases?) removed, or moved between releases?)
**Searchability** ### Searchability
- Does the duplication of pages affect search results? How do you manage result - Does the duplication of pages affect search results? How do you manage result
priority between versions? priority between versions?
**Localization / Internationalization** ### Localization / Internationalization
- How does the added complexity of language/locale versions affect the version - How does the added complexity of language/locale versions affect the version
system? system?
**Compartmentalization** ### Compartmentalization
- Does all of the site need to be versioned? - Does all of the site need to be versioned?
- How do we avoid versioning the entire site if only Documentation versions are - How do we avoid versioning the entire site if only Documentation versions are
the goal? the goal?
**Switchability**
- How easy is it to change versioning schemes?
## Versioning Schemes ## Versioning Schemes
For a Hugo / Netlify setup: For a Hugo / Netlify setup:
@ -223,12 +222,12 @@ method is likely the best method to balance versioning considerations.
[^1]: [^1]:
[Bannister, T.](https://github.com/sftim) et al. (2020, December 23). [Bannister, T.](https://github.com/sftim) et al. (2020, December 23).
kubernetes/website. GitHub. Retrieved February 2, 2021 from Kubernetes/website. GitHub. Retrieved February 2, 2021 from
[https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml) [https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml)
[^2]: [^2]:
[Batard, T.](https://github.com/tbatard) (2020, August 13). [Batard, T.](https://github.com/tbatard) (2020, August 13).
_vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from _VMware-Tanzu/velero_. GitHub. Retrieved January 19, 2021 from
[https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html) [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html)
[^3]: [^3]:
@ -236,13 +235,13 @@ method is likely the best method to balance versioning considerations.
[Rosland, J.](https://github.com/jonasrosland), [Rosland, J.](https://github.com/jonasrosland),
[Thompson, C.](https://github.com/carlisia), [Thompson, C.](https://github.com/carlisia),
[Batard, T.](https://github.com/tbatard) (2020, September 16). [Batard, T.](https://github.com/tbatard) (2020, September 16).
_vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from _VMware-Tanzu/velero_. GitHub. Retrieved February 2, 2021 from
[https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml) [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml)
[^4]: [^4]:
[Pursley, B.](https://github.com/brianpursley), [Pursley, B.](https://github.com/brianpursley),
[Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July [Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July
21). _kubernetes/website_. GitHub. Retrieved February 2, 2021 from 21). _Kubernetes/website_. GitHub. Retrieved February 2, 2021 from
[https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html) [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html)
--- ---

2
docs/website-guidelines-checklist.md
View File

@ -14,7 +14,7 @@ all projects
Unless there's a strong necessity to use CLA, we encourage projects to Unless there's a strong necessity to use CLA, we encourage projects to
use DCO as it's easier to setup and use. use DCO as it's easier to setup and use.
- [ ] 2. Reference the origin company correctly (if needed)<br/> _Note_: It is - [ ] 2. Reference the origin company correctly (if needed)<br/> _Note_: It is
OK to say that, e.g., “Prometheus was originally created by Soundcloud” or OK to say that, e.g., “Prometheus was originally created by SoundCloud” or
“Kubernetes builds upon 15 years of experience of running production “Kubernetes builds upon 15 years of experience of running production
workloads at Google,” but the origin company should not otherwise be workloads at Google,” but the origin company should not otherwise be
referred to on the project homepage. referred to on the project homepage.

2
package.json
View File

@ -18,7 +18,7 @@
"check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
"check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'", "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check@3.12.2 --config .markdown-link-check.json -p -v $f || exit 1; done'",
"check:markdown": "npm run _check:markdown:all", "check:markdown": "npm run _check:markdown:all",
"check:spelling": "npx cspell --no-progress -c .cspell.yml *.md", "check:spelling": "npx cspell --no-progress -c .cspell.yml analyses docs *.md",
"check": "npm run seq -- $(npm run -s _list:check:*)", "check": "npm run seq -- $(npm run -s _list:check:*)",
"fix:format": "npm run _check:format -- --write", "fix:format": "npm run _check:format -- --write",
"fix": "npm run seq -- $(npm -s run _list:fix:*)", "fix": "npm run seq -- $(npm -s run _list:fix:*)",