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

12
analyses/0001-contour.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Horgan celestehorgan hashlinks
---
# Docs assessment
## Introduction
@ -174,8 +178,8 @@ website, and in the repo. Great job team!
- Update
[SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md)
to Hugo when ready.
- Do a backlog clean of `kind/docuentation` and ensure that all issues are still
valid. Close any which are not. For example
- Do a backlog clean of `kind/documentation` and ensure that all issues are
still valid. Close any which are not. For example
[this issue](https://github.com/projectcontour/contour/issues/2053) was opened
in 2019.
- 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
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
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
@ -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
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
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
Date: 2021-07-31 Project: [Notary Project](https://github.com/notaryproject/)
@ -223,8 +227,8 @@ developed?
_Note_:
[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
be developed.
exists. Other branding elements, like color schemes and whatnot, will need to be
developed.
### Information Architecture

18
analyses/0003-krator.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: Krator celestehorgan CODEOWNERS
---
# Krator Docs assessment
## Introduction
@ -53,9 +57,9 @@ Criteria:
- Documentation is currently in several locations and will need to be brought
into one repo. The current resources are:
- 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/)
- [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
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
@ -83,7 +87,7 @@ Criteria:
- We'll need to create a clear entry point for the new user. Some of this info
could be taken from the
[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.
- **Content maintainability**:
- 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.
- **Tutorials**
- **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
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:
- **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.
- **Best practices**
- **Troubleshooting**
- **Troubleshooting**
- **Error Reference** A table with explanations and resolution steps would
suffice
- **Contributing to krator**
- **Contributing to Krator**
- **Cutting releases** (This is existing documentation)
- **Contributing:** Include information on submitting issues and
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 -->
- **Maitenence planning**:
- **Maintenance planning**:
- **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
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
Prepared by: Celeste Horgan Date: July 2021

4
analyses/0005-fluxcd.md
View File

@ -1,3 +1,7 @@
---
cSpell:ignore: celestehorgan Horgan
---
# Assessment template
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
Prepared by: Meha Bhalodiya
@ -95,7 +99,7 @@ as well as where to find them.
- Reference
- Contribute
- **Prepared a miro board:
- **Prepared a Miro board:
[https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)**
![information_architecture](../docs/images/gapi_info_arch.png)

8
analyses/0007-porter.md
View File

@ -1,6 +1,6 @@
---
title: Porter tech docs assessment draft
tags: porter
cSpell:ignore: Uchechukwu Obasi
---
# Notes
@ -103,7 +103,7 @@ Scale:
- Multiple OSes are well documented too.
- The onboarding and contributing guides are well documented making it easy for
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.
- Items listed under "When to use Porter?" are inconsistent with the way they're
linked: some are linked while others are not.
@ -122,7 +122,7 @@ Scale:
developers to write docs. I think it's a fair point. My only issue with this
convention is that it makes it difficult for a new contributor to find the
website's sourcefile. A contributor expects the "docs" directory to only
contain nothing but actual documentation files not website sourcefiles.
contain nothing but actual documentation files not website source files.
- There's no way to search the documentation
- Hard to locate the different versions on smaller screens
@ -140,7 +140,7 @@ Scale:
- Overall, Porter's documentation is well organized:
- 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
there -- search may help with findability
there -- search may help with discoverability
- Best practices could be under reference
- 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
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

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
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
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
[ITE repo](https://github.com/in-toto/ITE/). The document should be
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.
## Establish policy for reference material

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

@ -1,3 +1,7 @@
---
cSpell:ignore: roadmaps Cappos
---
# Implementation
## Organizational principles
@ -53,15 +57,15 @@ site should explicitly direct users of different types to relevant sections.
Users with the following roles are potential audiences for in-toto project
documentation.
| 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. |
| **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. |
| **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. |
| **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. |
| **Doc contributors** (to be added) are members of the community who use the **Edit** button to make changes to published documents, or create new documentation. | These contributors need clear doc contribution standards, naming and style conventions, and clear instructions on how to create or edit existing doc, and where documents should go (that is, what should go on the website or in GitHub, where a subject fits in the doc architecture) |
| 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. |
| **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 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??_ |
| **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. |
| **Doc contributors** (to be added) are members of the community who use the **Edit** button to make changes to published documents, or create new documentation. | These contributors need clear doc contribution standards, naming and style conventions, and clear instructions on how to create or edit existing doc, and where documents should go (that is, what should go on the website or in GitHub, where a subject fits in the doc architecture) |
## General doc plan
@ -210,10 +214,10 @@ following general plan.
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
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
index accordingly and adjust the doc architecture as needed.
4.4 As documents are transferred from GitHub into the Doc web site, update
the index accordingly and adjust the doc architecture as needed.
5. Reference material

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

@ -4,6 +4,7 @@ tags: etcd
created: 2023-09-01
modified: 2024-01-08
author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch
---
# Introduction
@ -23,14 +24,14 @@ efforts.
This document was written to analyze the current state of etcd documentation. It
aims to provide project leaders with an informed understanding of potential
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:
- Analyzes the current etcd technical documentation and website
- Compares existing documentation against the CNCF’s standards
- 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
presentation of documentation
@ -94,7 +95,7 @@ to their area of concern:
- [Project documentation][proj-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
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)
developers, and 2) operators or admins responsible for running and maintaining
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
course of performning a task.
course of performing a task.
For an excellent and very literal example of this approach, see the [Kubernetes
documentation][k8s-doc].
@ -507,7 +508,7 @@ minimal difficulty **finding help** if they need it.
### Project governance documentation
[**Project goverance**][etcd-govern] is clearly documented.
[**Project governance**][etcd-govern] is clearly documented.
## Recommendations
@ -527,7 +528,7 @@ repo, with links to the other contributor resources.
### Project governance documentation
No recommnendations.
No recommendations.
# Website
@ -682,8 +683,7 @@ documentation for all major use cases for each stakeholder.
### Usability, accessibility and devices
Consider replaciing low-contrast text for the benefit of visually impaired
users.
Consider replacing low-contrast text for the benefit of visually impaired users.
### Branding and design

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

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

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

@ -1,6 +1,6 @@
---
title: etcd Umbrella Issue
tags: etcd
cSpell:ignore: reconf
---
# Overview
@ -334,13 +334,13 @@ section is probably easier.
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
that don't fit elesewhere.
that don't fit elsewhere.
## Issue: Create a System Overview
Rename the "Learning" section to "System Overview" or "Conceptual Overview".
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.
Move the section to earlier in ToC, perhaps before "Installation".
@ -353,8 +353,8 @@ Include in architecture overview.
### etcd client design
Include in architecture overview. Remove the Glossary and merge it into the
sitewide Glossary.
Include in architecture overview. Remove the Glossary and merge it into the site
wide Glossary.
### etcd learner design

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

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

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

@ -4,9 +4,10 @@ tags: TUF
created: 2024-06-17
modified: YYYY-MM-DD
author: Sandra Dindi (@Dindihub)
cSpell:ignore: Dindi Dindihub RSTUF theupdateframework
---
<!-- markdownlint-disable no-duplicate-heading no-empty-links -->
<!-- markdownlint-disable no-duplicate-heading -->
## Introduction
@ -109,7 +110,7 @@ to their area of concern:
- [Contributor documentation](#contributor-documentation)
- [Website and infastructure](#website-and-infrastructure)
- [Website and infrastructure](#website-and-infrastructure)
#### Recommendations, requirements, and best practices
@ -168,7 +169,7 @@ Scale:
- 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
videos explaining various use cases.
@ -214,7 +215,7 @@ Scale:
#### Content maintainability & site mechanics
- 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
markdown. However,it appears the updates are made manually.
@ -242,7 +243,7 @@ Scale:
_Aborted_ is used in the
[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
@ -453,9 +454,9 @@ the website repo.
- Information about the website build, tools and how to generate it are not
available on the website or the docs repo.
- 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.
- Alot of empty space between the Hero section and the Navbar. Due to this
spacing, information is pushed out of eyelevel. You have to scroll down to
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
spacing, information is pushed out of eye level. You have to scroll down to
find it.
#### Single-source requirement
@ -477,7 +478,7 @@ The website docs analysis is in progress.
#### Branding and design
- 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
reducing the space between the hero section and the Navbar.
@ -511,7 +512,7 @@ The website docs analysis is in progress.
#### Branding and design
- Reduce the empty space between the hero section and Navbar to bring
information to eyelevel. At the moment the information is too far down, you
information to eye level. At the moment the information is too far down, you
have to scroll to find it.
#### SEO, Analytics and site-local search

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

@ -1,12 +1,12 @@
---
title: Implementing TUF Doc Improvements
tags: TUF
cSpell:ignore: RSTUF
---
## Introduction
This document provides actionable suggestions for improving the
**theUpdateframework (TUF)** technical documentation.
This document provides actionable suggestions for improving the **The Update
Framework (TUF)** technical documentation.
For an analysis and general discussion of recommendations on TUF technical
documentation, see [analysis](./analysis.md).
@ -157,7 +157,7 @@ it easier for contributors to contact them.
### Add labels to the website repo
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
@ -176,7 +176,7 @@ some good suggestions.
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
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

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

@ -1,6 +1,6 @@
---
title: TUF Issue
tags: TUF
cSpell:ignore: theupdateframework
---
## Overview
@ -16,10 +16,10 @@ analysis and implementation plan.
### Reorganize website content
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)
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
[theupdateframework.io](https://theupdateframework.io/)
@ -36,7 +36,7 @@ These can be further broken down into subsections depending on use case:
- Adopters :
- Client maintainers
- Respository maintainers
- Repository maintainers
- Contributors:
- Spec contributors
- Docs contributors
@ -49,7 +49,7 @@ repository for doc contributors.
Audience: Admin
Type: Conseptual
Type: Conceptual
### Add introductory Video to homepage
@ -58,7 +58,7 @@ Type: Conseptual
Audience: Admin
Type: Conseptual
Type: Conceptual
### Add a 'Schedule and appointment' icon to the website
@ -67,7 +67,7 @@ Type: Conseptual
Audience: Admin
Type: Conseptual
Type: Conceptual
### Introduce Instructional material for user roles
@ -115,8 +115,8 @@ Type: Conceptual
### Add labels to the website repo
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
for contributors to get started.
identify suitable issues. Labels such as `docs` and `good first issue` make it
easier for contributors to get started.
Audience: Admin

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

@ -4,7 +4,8 @@ tags: LitmusChaos
created: 2024-08-02
modified: 2024-10-09
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 -->
@ -255,7 +256,7 @@ Instructions for contributing doc changes are in the CONTRIBUTING.md file in the
docs repo.
There is nothing in the main release process about documentation. There is a
wikiin the main project repo. One of the things it contains is a list of SIGs
wiki in the main project repo. One of the things it contains is a list of SIGs
and one of the SIGs is documentation. However, the SIG document has not been
edited since early 2021.
@ -266,7 +267,7 @@ MAINTAINERS.md file.
There are a few examples of non-recommended words as documented by the
[Inclusive Naming Initiative](https://inclusivenaming.org) website. Some of
these cannot be summarily changed because they appear in pathnames, commands,
these cannot be summarily changed because they appear in path names, commands,
and as parameter names.
The project also uses terms like "simple", "easy", and so on in what could be
@ -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
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.

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

@ -3,6 +3,7 @@ title: Implementing LitmusChaos Doc Improvements
tags: LitmusChaos
created: 2024-10-24
author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch
---
<!-- markdownlint-disable no-duplicate-heading -->
@ -152,7 +153,7 @@ be its own page.
[Harness](https://app.harness.io/auth/#/signin).
- **Local** (self-hosted): Use _Helm_ or `kubectl`
- **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.
- **Advanced installation**: One-page install procedure.
- **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".
- Rather than duplicating information in different scenarios (basic vs. advanced
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.
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.
For example, the current documentation uses "Prerequisites" and "Before you
begin" for the same information.

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

@ -1,6 +1,6 @@
---
title: Litmus Chaos Issue
tags: Litmus Chaos
cSpell:ignore: litmuschaos ChaoCenter
---
<!-- 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
lesser liability than trying to maintain the same information in two (or more)
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
for that like the Restructured Text ".. include" directive.)
@ -327,7 +327,7 @@ same sections as shown for the User Guides in the TOC:
- Environments
- Chaos Infrastructure
- Injecting Fault
- Resilience Probjes
- Resilience Probes
- Account Settings
- User Management
- Managing Projects
@ -349,7 +349,7 @@ sections as shown for Concepts in the TOC:
- GitOps
- 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
capitalization; "Chaos Experiment" is title capitalization. Pick one or the
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
to the experiment execution page where the experiment execution steps are
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".
- 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
begin" for the same information.
- Similarly, retitle "Learn More" as "Next Steps", and write explanations for
@ -575,7 +575,7 @@ the relevant portion.
### Overview
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
should be included in the Litmus technical documentation so they are findable by
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?
- Is your new user content clearly signposted on your site’s homepage or at the
top of your information architecture?
- Is there easily copy-pastable sample code or other example content?
<!-- markdownlint-enable line-length -->
<!-- cSpell:ignore OSes copy-pastable Algolia Docsy -->
- Is there sample code or other example content that can easily be copy-pasted?
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
is working on tech doc analyses), and where _PROJECT_ is a short but not
abbreviated project name. For example, for Kubernetes _PROJECT_ would be
_kubernetes_, not _k8s_.
_Kubernetes_, not _k8s_.
4. Copy all the doc analysis [templates].
### 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_
documentation. It aims to provide project leaders with an informed understanding
of potential problems in current project documentation. A second [impementation]
document, , outlines an actionable plan for improvement. A third document is an
[issues list] of issues to be added to the project documentation repository.
These issues can be taken up by contributors to improve the documentation.
of potential problems in current project documentation. A second
[implementation] document, , outlines an actionable plan for improvement. A
third document is an [issues list] of issues to be added to the project
documentation repository. These issues can be taken up by contributors to
improve the documentation.
This document:
@ -62,7 +63,7 @@ the technical documentation, and documentation for contributors and users on the
_PROJECT_ GitHub repository.
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
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?
- Is your new user content clearly signposted on your site’s homepage or at the
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
@ -381,7 +382,7 @@ and documentation infrastructure rubric.
> these criteria. Keep in mind that much of the website infrastructure criteria
> depend on the tools (static site generator, website framework and hosting,
> 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)
#### Single-source requirement

4
docs/analytics.md
View File

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

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

@ -1,21 +1,25 @@
---
cSpell:ignore: caniszczyk
---
# Netlify and domain setup
## Netlify
If a project already has its own Netlify instance, ask them to add
@celestehorgan and @caniszczyk as administrators. As a part of their project
onboarding, any billing information should be taken care of. If it isn't, ask
them to open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket.
[@caniszczyk][] as administrator. As a part of project onboarding, any billing
information should be taken care of. If it isn't, ask them to open a
[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
Netlify, create a new site for them under the CNCF Projects netlify instance.
### 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
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.
## Domains
@ -30,7 +34,7 @@ one.
In most cases, we prefer to manage domains for project websites using Netlify
DNS.
At the moment, @caniszczyk manages domain transfers.
At the moment, [@caniszczyk][] manages domain transfers.
### 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.
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
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).
```
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
[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.
- [Google search](#programmable-search-engine-by-google)
- [Docsearch by Algolia](#docsearch-by-algolia)
- [DocSearch by Algolia](#docsearch-by-algolia)
- [Lunr](#lunr)
## Programmable Search Engine by Google
@ -26,7 +26,7 @@ website.
- 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
Algolia search engine that crawls your docs and provides a dropdown search
@ -61,8 +61,8 @@ needing external, server-side, search services.
### Cons
- Can be complex to configure and setup (If a team is already using hugo/docsy,
this should be _very_ easy to setup).
- Can be complex to configure and setup (If a team is already using Hugo or
Docsy, this should be _very_ easy to setup).
- Depending on site setup, may require javascript knowledge
## 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
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.

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:
@ -20,45 +23,41 @@ Things discussed in this article:
What are the main concerns when versioning technical documentation in a website?
**Readers**
### Readers
- Ease of navigation/understanding
**Maintainers / Writers**
### Maintainers / Writers
- How hard is it to update when it's time to cut a new version?
**Necessity**
### Necessity
- Does the documentation need versioning yet?
- YAGNI (You aren't gonna need it - Don't implement things before you actually
need them)
**Navigation**
### Navigation
- Differences between versions (how do you deal with pages that have been added,
removed, or moved between releases?)
**Searchability**
### Searchability
- Does the duplication of pages affect search results? How do you manage result
priority between versions?
**Localization / Internationalization**
### Localization / Internationalization
- How does the added complexity of language/locale versions affect the version
system?
**Compartmentalization**
### Compartmentalization
- Does all of the site need to be versioned?
- How do we avoid versioning the entire site if only Documentation versions are
the goal?
**Switchability**
- How easy is it to change versioning schemes?
## Versioning Schemes
For a Hugo / Netlify setup:
@ -223,12 +222,12 @@ method is likely the best method to balance versioning considerations.
[^1]:
[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)
[^2]:
[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)
[^3]:
@ -236,13 +235,13 @@ method is likely the best method to balance versioning considerations.
[Rosland, J.](https://github.com/jonasrosland),
[Thompson, C.](https://github.com/carlisia),
[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)
[^4]:
[Pursley, B.](https://github.com/brianpursley),
[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)
---

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
use DCO as it's easier to setup and use.
- [ ] 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
workloads at Google,” but the origin company should not otherwise be
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: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: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:*)",
"fix:format": "npm run _check:format -- --write",
"fix": "npm run seq -- $(npm -s run _list:fix:*)",