diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md index 22efb6f0..6c3d20c2 100644 --- a/analyses/0010-etcd/etcd-analysis.md +++ b/analyses/0010-etcd/etcd-analysis.md @@ -313,8 +313,8 @@ For example: - [installation check][install-check]: contains "sanity check", a term designated "Strongly Consider Replacing" by the [Inclusive Naming Initiative][inclusive-naming]. -- There is some use of language like "easy", "simple", and "just [take - an action]"; for example, "Creating a user is as easy as" in +- There is some use of language like "easy", "simple", and "just [take an + action]"; for example, "Creating a user is as easy as" in [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/). ## Recommendations diff --git a/analyses/0013-litmuschaos/litmuschaos-analysis.md b/analyses/0013-litmuschaos/litmuschaos-analysis.md index 462f2986..2cc2974c 100644 --- a/analyses/0013-litmuschaos/litmuschaos-analysis.md +++ b/analyses/0013-litmuschaos/litmuschaos-analysis.md @@ -4,11 +4,9 @@ tags: LitmusChaos created: 2024-08-02 modified: 2024-10-09 author: Dave Welsch (@dwelsch-esi) +cSpell:ignore: Docusaurus rfc OSes pastable impl servicedesk md --- - - - ## Introduction @@ -30,8 +28,9 @@ This document was written to analyze the current state of LitmusChaos documentation. It aims to provide project leaders with an informed understanding 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. +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,9 +61,9 @@ GitHub repo. #### Out of scope -- Other LitmusChaos repos: \* +- Other LitmusChaos repos: - Litmus Software (a completely unrelated company and product based in - Massachusetts): https://litmus.com/* + Massachusetts): ### How this document is organized @@ -172,9 +171,9 @@ installation, configuration, and running a "first-time" experiment. - Formatting and organization of the instructions is inconsistent. - Some minor functionality does not have complete step-by-step instructions. For example, a link in the instructions to connect an external delegate in - _Schedule a chaos scenario_ - point to the `litmusctl` reference. While relevant, this is not the same as - explicit instructions for connecting to a delegate. + _Schedule a chaos scenario_ point to the `litmusctl` reference. While + relevant, this is not the same as explicit instructions for connecting to a + delegate. @@ -292,7 +291,7 @@ complete. For complex procedures, it's OK to link to sub-procedures or (usually better) put preliminary tasks in the Prerequisites section. Ensure that installation, setup, and verification have a clear, linked path for -each user role. See [New user content](#New-user-content) below. +each user role. See [New user content](#new-user-content) below. Organize the User Guide by task. Some of the tasks will align with the current function-based organization, but some will not. If necessary, split it into two @@ -604,12 +603,12 @@ websites: -| Site | Repository | Tool or Stack | -|-----------| -------------------------------------------------------- | ------------------------ | -| [Project website](https://litmuschaos.io/) | https://github.com/litmuschaos/litmus-website-2 | React/Next/Tailwind/SCSS | -| [Documentation website](https://docs.litmuschaos.io/) | https://github.com/litmuschaos/litmus-docs/ | Docusaurus/Netlify | -| Tutorials | https://github.com/litmuschaos/tutorials | Google Codelab? | -| [APIs][api-site] | https://github.com/litmuschaos/litmus/tree/master/mkdocs | MkDocs | +| Site | Repository | Tool or Stack | +| ----------------------------------------------------- | ---------------------------------------------------------- | ------------------------ | +| [Project website](https://litmuschaos.io/) | | React/Next/Tailwind/SCSS | +| [Documentation website](https://docs.litmuschaos.io/) | | Docusaurus/Netlify | +| Tutorials | | Google Codelab? | +| [APIs][api-site] | | MkDocs | diff --git a/analyses/0013-litmuschaos/litmuschaos-implementation.md b/analyses/0013-litmuschaos/litmuschaos-implementation.md index 6510cbd5..4b09d7bf 100644 --- a/analyses/0013-litmuschaos/litmuschaos-implementation.md +++ b/analyses/0013-litmuschaos/litmuschaos-implementation.md @@ -23,10 +23,10 @@ things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology -from the lexicon of [RFCs][rfc-keywords], the changes described here should be -understood as "recommended" or "should" at the strongest, and "optional" or -"may" in many cases. Any "must" or "required" actions are clearly denoted as -such, and pertain to legal requirements such as copyright and licensing issues. +from the lexicon of [RFCs][], the changes described here should be understood as +"recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. ## Implementation @@ -129,11 +129,11 @@ There are at least four "getting started" links on the website. | Link | Location | Refers to | | --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | -| _Get Started_ button | [Product landing page](https://litmuschaos.io/) | [GitHub repo]() | +| _Get Started_ button | [Product landing page](https://litmuschaos.io/) | [GitHub repo](https://github.com/litmuschaos/litmus) | | _Get Started_ button | [Doc landing page](https://docs.litmuschaos.io/) | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation) | | _Getting Started_ link | [Doc landing page](https://docs.litmuschaos.io/) | [What is Litmus?](https://docs.litmuschaos.io/docs/introduction/what-is-litmus) | | _Getting Started_ TOC entry | [Doc page](https://docs.litmuschaos.io/docs/) left-side menu | [ChaosCenter installation](https://docs.litmuschaos.io/docs/getting-started/installation) | -| _Getting started_ tutorial | Tutorial site | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) | +| _Getting started_ tutorial | Tutorial site | [Getting started tutorial](https://litmuschaos.github.io/tutorials/tutorial-getting-started/index.html#0) | @@ -160,9 +160,10 @@ be its own page. Ensure that installation, setup, and verification have a clear workflow. If these instructions vary significantly between user roles, write a separate -workflow for each user role. See [New user content](#new-user-content) below. -Rename "Learn more" at the end of procedures and tasks to "Next steps". Explain -who would want to do each item and why in a short paragraph. +workflow for each user role. See +[New user content](litmuschaos-analysis.md#new-user-content). Rename "Learn +more" at the end of procedures and tasks to "Next steps". Explain who would want +to do each item and why in a short paragraph. Limit on-site search to the current version of the documentation. @@ -252,3 +253,5 @@ Consider adding links from the graphic elements on the project landing page. Update or remove the CNCF announcement in the banner menu Community drop-down. Implement analytics. + +[RFCs]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0013-litmuschaos/litmuschaos-issues.md b/analyses/0013-litmuschaos/litmuschaos-issues.md index ef9958df..4df5b48b 100644 --- a/analyses/0013-litmuschaos/litmuschaos-issues.md +++ b/analyses/0013-litmuschaos/litmuschaos-issues.md @@ -3,6 +3,8 @@ title: Litmus Chaos Issue tags: Litmus Chaos --- + + This document contains a list of issues to be entered in the Litmus Chaos documentation repo more or less verbatim. @@ -43,13 +45,13 @@ are here: under The following repos are affected: -| Repo URL | Description | Recommendation | -| -------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | -| https://github.com/litmuschaos/litmus-website-2 | The project website repo | Combine with the doc repo | -| https://github.com/litmuschaos/litmus-docs | Documentation repo | Combine with website repo | -| https://github.com/litmuschaos/v1-litmus-docs | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving. | -| https://github.com/litmuschaos/website-litmuschaos | Previous website repo | Already archived. Include new repo URL in archive banner. | -| https://github.com/litmuschaos/tutorials | Tutorials repo | Combine with documentation repo | +| Repo URL | Description | Recommendation | +| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | +| | The project website repo | Combine with the doc repo | +| | Documentation repo | Combine with website repo | +| | Another documentation repo, for docs before 2.0 | Move toward retiring and archiving. | +| | Previous website repo | Already archived. Include new repo URL in archive banner. | +| | Tutorials repo | Combine with documentation repo | ## Issue: Removed obsolete websites @@ -83,17 +85,17 @@ are here: under **GraphicQL API** The following API is one of the first hits on a search of "Litmus Chaos API": -https://litmuschaos.github.io/litmus/graphql/v2.0.0/api.html. +. -I'm not even sure where the doc repo is (it might be in the API's repo here: -https://github.com/litmuschaos/spectaql). It's clear this is a Litmus Chaos -component, but not whether this documetnation is current or what it is for -- +I'm not even sure where the doc repo is (it might be in the API's repo at +). It's clear this is a Litmus Chaos +component, but not whether this documentation is current or what it is for -- there's no introduction or explanation of the API. **Tutorials** -The Litmus Chaos Tutorial website (https://litmuschaos.github.io/tutorials/; -repo at https://github.com/litmuschaos/tutorials) seems to have been last +The [Litmus Chaos Tutorial website](https://litmuschaos.github.io/tutorials/) +([repo](https://github.com/litmuschaos/tutorials)) seems to have been last updated in version 2. The first tutorial, "Getting Started", was last updated in August of 2021. diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index d17bafb0..40b6102a 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -12,8 +12,8 @@ The goals of a CNCF technical documentation analysis are to: - Examine the current project technical documentation and website against the CNCF's analysis [criteria]. -- Compare the documentation against the current or proposed [project - maturity level]. +- Compare the documentation against the current or proposed [project maturity + level]. - Recommend a program of key documentation improvements with the largest return on investment. These improvements are documented as _recommendations_ in the analysis document, and expanded in a companion diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index a7c1b2d7..b975ae59 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -46,8 +46,8 @@ 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. +[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: @@ -61,23 +61,23 @@ The documentation discussed here includes the entire contents of the website, 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 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. +The _PROJECT_ website and documentation are written in [Markdown, ReStructured +Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, 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. #### In scope - Website: _PROJECT-WEBSITE_ - Documentation: _PROJECT-DOC-URL_ - Website repo: _PROJECT-DOC-REPO_ -- _[Other; might include a demo server, governance site, or other relevant repositories]_ +- _[Other; might include a demo server, governance site, or other relevant + repositories]_ #### Out of scope -- Other _PROJECT_ repos: _[In general, do not include sub-projects or - related "ecosystem" projects]_ +- Other _PROJECT_ repos: _[In general, do not include sub-projects or related + "ecosystem" projects]_ ### How this document is organized diff --git a/docs/analytics.md b/docs/analytics.md index 3836b977..bd85d11d 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -33,8 +33,8 @@ process below. Adapt it to your needs. Useful resources to consider include: In preparation for the migration, follow these steps: 1. **Create an issue** over your project's website with the title "Migrate to - Google Analytics 4 (GA4)", and link to [Issue #108][]. For example, see the issues - opened for the pilot projects listed in #108. + Google Analytics 4 (GA4)", and link to [Issue #108][]. For example, see the + issues opened for the pilot projects listed in #108. 2. Determine which **analytics library** your project's website is using. @@ -69,8 +69,8 @@ Follow these steps: How you switch will depend on the static-site generation tooling you use. For details, see [Stage 2][]. If you know how to switch and it is easy to do - so, then switch your project to [gtag.js][], otherwise defer the switch to [stage - 2][]. + so, then switch your project to [gtag.js][], otherwise defer the switch to + [stage 2][]. 2. **Open the analytics console** of your project's UA property by visiting [analytics.google.com](https://analytics.google.com). @@ -179,9 +179,9 @@ code (such as custom Hugo partials) to enable GA4, consider removing the custom code in favor of the native support provided by your site-generator tooling. For example, for [Docsy][]-based websites, all you need to do is provide your -project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of course, -this may require you to upgrade the version of [Docsy][] and/or Hugo that your project -is using. +project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of +course, this may require you to upgrade the version of [Docsy][] and/or Hugo +that your project is using. [add gtag.js to your site]: https://developers.google.com/analytics/devguides/collection/gtagjs/ diff --git a/package.json b/package.json index 7808dc68..ef59e19c 100644 --- a/package.json +++ b/package.json @@ -16,26 +16,29 @@ "_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'", "_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'", "check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)", - "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check --config .markdown-link-check.json $f || exit 1; done'", + "check:links": "bash -c 'for f in *.md `find docs analyses -name \"*.md\"`; do npx markdown-link-check@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": "npm run seq -- $(npm run -s _list:check:*)", "fix:format": "npm run _check:format -- --write", "fix": "npm run seq -- $(npm -s run _list:fix:*)", "seq": "bash -c 'for cmd in \"$@\"; do npm run $cmd || exit 1; done' - ", - "test": "npm run check" + "test": "npm run check", + "update:pkgs": "npx npm-check-updates -u" }, "author": "CNCF", "license": "CC-BY-4.0", + "NOTE": "We've pinned markdown-link-check to 3.12.2 due to a bug in 3.13.x stream, both in the devDeps below and the check:links script above. For details, see https://github.com/tcort/markdown-link-check/issues/369.", "devDependencies": { - "cspell": "^8.8.4", - "markdown-link-check": "^3.12.2", - "markdownlint": "^0.34.0", - "markdownlint-cli": "^0.41.0", - "prettier": "^3.3.2" + "cspell": "^8.17.5", + "markdown-link-check": "3.12.2", + "markdownlint": "^0.37.4", + "markdownlint-cli": "^0.44.0", + "npm-check-updates": "^17.1.15", + "prettier": "^3.5.2" }, "private": true, - "spelling": "cSpell:ignore ACMR loglevel -", + "spelling": "cSpell:ignore ACMR loglevel pkgs -", "prettier": { "proseWrap": "always", "singleQuote": true