mirror of https://github.com/cncf/techdocs.git
[CI] Update packages and run checks and fixes (#287)
This commit is contained in:
Patrice Chalin
GitHub
parent
a4f745b293
commit
ac83b89179
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
<!-- cSpell:ignore Docusaurus rfc OSes pastable impl servicedesk md -->
|
||||
|
||||
<!-- markdownlint-disable no-duplicate-heading -->
|
||||
|
||||
## 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: <https://github.com/litmuschaos/>\*
|
||||
- Other LitmusChaos repos: <https://github.com/litmuschaos/>
|
||||
- Litmus Software (a completely unrelated company and product based in
|
||||
Massachusetts): https://litmus.com/*
|
||||
Massachusetts): <https://litmus.com/>
|
||||
|
||||
### 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.
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
|
||||
|
|
@ -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:
|
|||
|
||||
<!-- markdownlint-disable line-length -->
|
||||
|
||||
| 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/) | <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 |
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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) |
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -3,6 +3,8 @@ title: Litmus Chaos Issue
|
|||
tags: Litmus Chaos
|
||||
---
|
||||
|
||||
<!-- markdownlint-disable line-length no-duplicate-heading no-emphasis-as-heading -->
|
||||
|
||||
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: <https://github.com/cncf/techdocs/tree/main/analyses> 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 |
|
||||
| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
|
||||
| <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 |
|
||||
|
||||
## Issue: Removed obsolete websites
|
||||
|
||||
|
|
@ -83,17 +85,17 @@ are here: <https://github.com/cncf/techdocs/tree/main/analyses> 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.
|
||||
<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
|
||||
<https://github.com/litmuschaos/spectaql>). 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
|
|
|
|||
19
package.json
19
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue