Skip to content

Commit

Permalink
[chore] Enable spell-check and fix spelling
Browse files Browse the repository at this point in the history
Signed-off-by: Patrice Chalin <pchalin@gmail.com>
  • Loading branch information
chalin committed Feb 26, 2025
1 parent 706bc26 commit 74f1c4c
Show file tree
Hide file tree
Showing 33 changed files with 184 additions and 137 deletions.
9 changes: 6 additions & 3 deletions .cspell.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand All @@ -22,9 +21,13 @@ ignorePaths:
# - CodeBlock
words:
- backstore
- CLOTributor
- CNCF
- Docsy
- keda
- kedacore
- subpages
- techdocs
- toolkits
- toto
- triaging
12 changes: 8 additions & 4 deletions analyses/0001-contour.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: Horgan celestehorgan hashlinks
---

# Docs assessment

## Introduction
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down
8 changes: 6 additions & 2 deletions analyses/0002-notary-project.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: docset notaryproject celestehorgan
---

# Notary Project Docs Assessment

Date: 2021-07-31 Project: [Notary Project](https://github.com/notaryproject/)
Expand Down Expand Up @@ -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

Expand Down
18 changes: 11 additions & 7 deletions analyses/0003-krator.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: Krator celestehorgan CODEOWNERS
---

# Krator Docs assessment

## Introduction
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions analyses/0004-tremor.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: Horgan onramps offramps LLDB Wayfair
---

# Assessment: Project Tremor

Prepared by: Celeste Horgan Date: July 2021
Expand Down
4 changes: 4 additions & 0 deletions analyses/0005-fluxcd.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: celestehorgan Horgan
---

# Assessment template

Prepared by: Celeste Horgan
Expand Down
6 changes: 5 additions & 1 deletion analyses/0006-gateway-api.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
cSpell:ignore: Meha Bhalodiya mehabhalodiya kubernetes
---

# Assessment: Project Kubernetes Gateway API

Prepared by: Meha Bhalodiya
Expand Down Expand Up @@ -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)
Expand Down
8 changes: 4 additions & 4 deletions analyses/0007-porter.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Porter tech docs assessment draft
tags: porter
cSpell:ignore: Uchechukwu Obasi
---

# Notes
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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?

Expand Down
2 changes: 1 addition & 1 deletion analyses/0008-backstage/user-roles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion analyses/0009-in-toto/in-toto-analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions analyses/0009-in-toto/in-toto-doc-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 74f1c4c

Please sign in to comment.