From 4c737cf353c57b43834b50de97a93b613a182c02 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 26 Feb 2025 04:45:07 -0500 Subject: [PATCH] [chore] Enable spell-check and fix spelling --- .cspell.yml | 9 +++-- analyses/0001-contour.md | 12 ++++--- analyses/0002-notary-project.md | 8 +++-- analyses/0003-krator.md | 18 ++++++---- analyses/0004-tremor.md | 4 +++ analyses/0005-fluxcd.md | 4 +++ analyses/0006-gateway-api.md | 6 +++- analyses/0007-porter.md | 8 ++--- analyses/0008-backstage/user-roles.md | 2 +- analyses/0009-in-toto/in-toto-analysis.md | 2 +- analyses/0009-in-toto/in-toto-doc-issues.md | 4 +-- .../0009-in-toto/in-toto-implementation.md | 28 +++++++++------- analyses/0010-etcd/etcd-analysis.md | 18 +++++----- analyses/0010-etcd/etcd-implementation.md | 6 ++-- analyses/0010-etcd/etcd-issues.md | 10 +++--- analyses/0012-TUF/README.md | 4 +++ analyses/0012-TUF/analysis.md | 21 ++++++------ analyses/0012-TUF/implementation.md | 10 +++--- analyses/0012-TUF/issues.md | 18 +++++----- .../0013-litmuschaos/litmuschaos-analysis.md | 9 ++--- .../litmuschaos-implementation.md | 7 ++-- .../0013-litmuschaos/litmuschaos-issues.md | 16 ++++----- docs/analysis/criteria.md | 5 +-- docs/analysis/howto.md | 2 +- docs/analysis/templates/analysis.md | 15 +++++---- docs/analytics.md | 4 ++- docs/netlify-domains-setup.md | 18 ++++++---- docs/repo-setup.md | 6 +++- docs/searching-documentation.md | 8 ++--- docs/services.md | 2 +- docs/versioning-documentation.md | 33 +++++++++---------- docs/website-guidelines-checklist.md | 2 +- package.json | 2 +- 33 files changed, 184 insertions(+), 137 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 714de68..759200b 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -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: | @@ -22,9 +21,13 @@ ignorePaths: # - CodeBlock words: - backstore + - CLOTributor - CNCF - Docsy - keda - kedacore + - subpages - techdocs + - toolkits - toto + - triaging diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index 76dfa25..1a2dfe3 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -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. diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index 692ca84..a36e23a 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -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 diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index c4cba3b..532e6fe 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -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! -- **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 diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 951cb92..94b3502 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -1,3 +1,7 @@ +--- +cSpell:ignore: Horgan onramps offramps LLDB Wayfair +--- + # Assessment: Project Tremor Prepared by: Celeste Horgan Date: July 2021 diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index 591c777..6f42aad 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -1,3 +1,7 @@ +--- +cSpell:ignore: celestehorgan Horgan +--- + # Assessment template Prepared by: Celeste Horgan diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index a9616df..f346292 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -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) diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index fbad169..4696349 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -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? diff --git a/analyses/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md index 611aa55..e749f48 100644 --- a/analyses/0008-backstage/user-roles.md +++ b/analyses/0008-backstage/user-roles.md @@ -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 diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md index aed5ff2..a7fd243 100644 --- a/analyses/0009-in-toto/in-toto-analysis.md +++ b/analyses/0009-in-toto/in-toto-analysis.md @@ -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. diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index fdc48cc..b4a3163 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -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 diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 8bb1ccf..98e9e11 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -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 diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md index 6c3d20c..c36d5ce 100644 --- a/analyses/0010-etcd/etcd-analysis.md +++ b/analyses/0010-etcd/etcd-analysis.md @@ -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 diff --git a/analyses/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md index bbce31c..3bee2d8 100644 --- a/analyses/0010-etcd/etcd-implementation.md +++ b/analyses/0010-etcd/etcd-implementation.md @@ -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". diff --git a/analyses/0010-etcd/etcd-issues.md b/analyses/0010-etcd/etcd-issues.md index 2359adb..123c5b8 100644 --- a/analyses/0010-etcd/etcd-issues.md +++ b/analyses/0010-etcd/etcd-issues.md @@ -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 diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 89b1d4a..7255225 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,3 +1,7 @@ +--- +cSpell:ignore: theupdateframework +--- + # TUF Documentation Analysis This section contains analysis of The Update Framework (TUF) project diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index e2b1bea..d68c4e4 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -4,9 +4,10 @@ tags: TUF created: 2024-06-17 modified: YYYY-MM-DD author: Sandra Dindi (@Dindihub) +cSpell:ignore: Dindi Dindihub RSTUF theupdateframework --- - + ## 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 diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 67ee6a3..e83c670 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -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 diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 9ffb2b8..9abe2c1 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -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 diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md index 2cc2974..ca7786f 100644 --- a/analyses/0013-litmuschaos/litmuschaos-analysis.md +++ b/analyses/0013-litmuschaos/litmuschaos-analysis.md @@ -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 --- @@ -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. diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/0013-litmuschaos/litmuschaos-implementation.md index 4b09d7b..5fe032b 100644 --- a/analyses/0013-litmuschaos/litmuschaos-implementation.md +++ b/analyses/0013-litmuschaos/litmuschaos-implementation.md @@ -3,6 +3,7 @@ title: Implementing LitmusChaos Doc Improvements tags: LitmusChaos created: 2024-10-24 author: Dave Welsch (@dwelsch-esi) +cSpell:ignore: Welsch dwelsch --- @@ -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. diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/0013-litmuschaos/litmuschaos-issues.md index 4df5b48..3f1fc84 100644 --- a/analyses/0013-litmuschaos/litmuschaos-issues.md +++ b/analyses/0013-litmuschaos/litmuschaos-issues.md @@ -1,6 +1,6 @@ --- title: Litmus Chaos Issue -tags: Litmus Chaos +cSpell:ignore: litmuschaos ChaoCenter --- @@ -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. diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index e6719fb..424bbea 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -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? - - - +- Is there sample code or other example content that can easily be copy-pasted? Example: diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index 40b6102..22018b5 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -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 diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index b975ae5..524a7ee 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -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 diff --git a/docs/analytics.md b/docs/analytics.md index bd85d11..2e7d5e7 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -1,4 +1,6 @@ - +--- +cSpell:ignore: gtag kubernetes +--- # Analytics diff --git a/docs/netlify-domains-setup.md b/docs/netlify-domains-setup.md index 2150de0..79db247 100644 --- a/docs/netlify-domains-setup.md +++ b/docs/netlify-domains-setup.md @@ -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 diff --git a/docs/repo-setup.md b/docs/repo-setup.md index f9f062b..f3ee269 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -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) diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md index cc96298..c137ad2 100644 --- a/docs/searching-documentation.md +++ b/docs/searching-documentation.md @@ -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? diff --git a/docs/services.md b/docs/services.md index d11feff..b5c9d7e 100644 --- a/docs/services.md +++ b/docs/services.md @@ -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. diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index d679076..5acdc30 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -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 +--- - +# 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) --- diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index e8b8ace..050fcd5 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -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)
_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. diff --git a/package.json b/package.json index ef59e19..58206f8 100644 --- a/package.json +++ b/package.json @@ -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:*)",