From 79df3fc41b379eeba04f90942b86c90dc018a5b7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 12 Jun 2024 12:28:39 -0400 Subject: [PATCH] [CI & docs] Rework of analysis docs + improved checks Signed-off-by: Patrice Chalin --- .github/workflows/format-check.yml | 15 +- .markdownlint.yaml | 5 + README.md | 15 +- analyses/README.md | 2 +- docs/analysis/README.md | 12 +- docs/analysis/criteria.md | 29 +- docs/analysis/howto.md | 104 +++--- docs/analysis/templates/README.md | 7 +- docs/analysis/templates/analysis.md | 369 +++++++++++----------- docs/analysis/templates/implementation.md | 28 +- docs/analysis/templates/issue.md | 36 ++- docs/analysis/templates/issues-list.md | 52 +++ docs/analysis/templates/umbrella-issue.md | 35 -- docs/analytics.md | 39 ++- docs/repo-setup.md | 37 +-- docs/searching-documentation.md | 2 + docs/versioning-documentation.md | 9 +- docs/website-guidelines-checklist.md | 5 +- package.json | 12 +- 19 files changed, 440 insertions(+), 373 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 docs/analysis/templates/issues-list.md delete mode 100644 docs/analysis/templates/umbrella-issue.md diff --git a/.github/workflows/format-check.yml b/.github/workflows/format-check.yml index 986a6cf..ec4f130 100644 --- a/.github/workflows/format-check.yml +++ b/.github/workflows/format-check.yml @@ -14,5 +14,16 @@ jobs: node-version-file: .nvmrc cache: npm cache-dependency-path: package.json - - name: Check file format - run: npm run check:format + - run: npm run check:format + + markdown-linter: + name: MARKDOWN linter + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + cache: npm + cache-dependency-path: package.json + - run: npm run check:markdown diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..6eb808e --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,5 @@ +# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# and https://github.com/DavidAnson/markdownlint/blob/main/README.md + +list-marker-space: false +no-inline-html: false diff --git a/README.md b/README.md index 2b9a731..b19c2bf 100644 --- a/README.md +++ b/README.md @@ -13,27 +13,29 @@ team. The repo contains the following directories: The full-time staff of the CNCF Tech Docs team is: + + | GitHub ID | Role | | -------------------------------------------------- | ------------------------------------- | | [@chalin](https://github.com/chalin) | Senior technical writer | | [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | | [@thisisobate](https://github.com/thisisobate) | Developer advocate | + Various consultants and volunteers also contribute to CNCF Tech Docs projects. ## Office hours -The CNCF tech docs team holds office hours on the -[fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). +The CNCF tech docs team holds office hours on the [fourth Wednesday of every +month at 8am Pacific time][date-time]. Office hours started on 30 September 2020. ### Meeting link -Zoom link: -https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e +- [Zoom meeting 95471930872] ### Meeting notes @@ -51,3 +53,8 @@ documentation. For details, see the TechDocs The `docs/` directory contains collected resources for building websites and developing documentation, including recommended tools and practices, how-tos, and evaluation checklists. + +[date-time]: + https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours +[Zoom meeting 95471930872]: + https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e diff --git a/analyses/README.md b/analyses/README.md index 6126754..4ea831f 100644 --- a/analyses/README.md +++ b/analyses/README.md @@ -15,7 +15,7 @@ The goals of a CNCF technical documentation analysis are to: investment. These improvements are documented as _recommendations_ in the analysis document and expanded in a companion [implementation plan](../docs/analysis/templates/implementation.md) and - [issues backlog](../docs/analysis/templates/umbrella-issue.md). + [issues backlog](../docs/analysis/templates/issues-list.md). ## Audience diff --git a/docs/analysis/README.md b/docs/analysis/README.md index f6edd8f..195a967 100644 --- a/docs/analysis/README.md +++ b/docs/analysis/README.md @@ -1,11 +1,7 @@ # TechDoc Analysis -## Contents +This section contains instructions and criteria for completing a documentation +analysis, including a [how-to](./howto.md) guide and analysis +[criteria](./criteria.md) -This directory contains instructions and criteria for completing a documentation -analysis, including a [how-to][] guide and analysis [criteria][]. - -Templates for the analyses are in the resources directory. - -[how-to]: ./howto.md -[criteria]: ./criteria.md +For templates, see [templates](./templates/). diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index f605a72..c0c9e61 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -23,7 +23,7 @@ documentation. We evaluate on the following: Examples: -- https://prometheus.io/docs/ +- ### New user content @@ -41,7 +41,7 @@ specifically for them. We evaluate on the following: Examples: -- https://falco.org/docs/getting-started/ +- ### Content maintainability & site mechanics @@ -57,7 +57,7 @@ We evaluate on the following: Examples: -- https://kubernetes.io/docs/ +- ### Content creation processes @@ -74,9 +74,9 @@ We evaluate on the following: Examples: -- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly +- (clearly documented maintainers) -- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md +- ### Inclusive language @@ -107,7 +107,7 @@ We evaluate on the following: Examples: -- https://prometheus.io/community/ +- ### Beginner friendly issue backlog @@ -121,7 +121,7 @@ We evaluate on the following: Examples: -- https://github.com/opentracing/opentracing.io/issues (all of open tracing’s +- (all of open tracing’s backlogs are well maintained!) ### New contributor getting started content @@ -138,7 +138,7 @@ We evaluate on the following: Examples: -- https://github.com/helm/community +- ### Project governance documentation @@ -165,7 +165,8 @@ problems, keeping source files in two places: - makes it more complicated to generate the documentation from source files Ideally, all website files should be in the **website repo** itself. -Alternatively, files should be brought into the website repo via [git submodules][]. +Alternatively, files should be brought into the website repo via +[git submodules](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules). If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. @@ -257,7 +258,7 @@ We evaluate on the following: Examples: -- https://helm.sh/ +- ### Case studies/social proof @@ -275,9 +276,9 @@ We evaluate on the following: Examples: -- https://www.fluentd.org/testimonials (user testimonials) -- https://goharbor.io/ (logo wall) -- https://blog.rook.io/ (blog) +- (user testimonials) +- (logo wall) +- (blog) ### SEO, Analytics and site-local search @@ -314,7 +315,7 @@ We evaluate on the following: Examples: -- http://kubernetes.io +- ### Other diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index ff83ceb..d17bafb 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -2,75 +2,78 @@ ## Audience -This document is for members of the CNCF TechDocs team, including contractors or -consultants, who need to conduct or assist with an analysis of a CNCF -open-source project's technical documentation. +This document is for members of the CNCF TechDocs team and others who wish to +conduct or assist with an analysis of a CNCF open-source project's technical +documentation. ## Purpose The goals of a CNCF technical documentation analysis are to: - Examine the current project technical documentation and website against the - CNCF's analysis framework, as described in the doc analysis - [criteria](./criteria.md). -- Compare the documentation against the current or proposed maturity level for - the overall project. -- Recommends a program of key improvements with the largest return on - investment. These improvements are documented as _recommendations_ in the - analysis document and expanded in a companion + CNCF's analysis [criteria]. +- 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 [implementation plan](./templates/implementation.md) and - [issues backlog](./templates/umbrella-issue.md). + [issues list](./templates/issues-list.md). ## Doing a Tech Docs Analysis -The tech docs analysis consists of some repository bookkeeping (Prerequisites), +The tech docs analysis consists of some repository bookkeeping (prerequisites), then of three overall tasks: -1. Write the analysis document: Evaluate the existing project documentation with - respect to the project maturity level (or proposed maturity level, if the - analysis is associated with an upgrade request). Identify gaps with CNCF - criteria. Write general recommendations to close the largest and most - important gaps. -2. Write the implementation plan: Decompose the recommendations to specific +1. Write the analysis document: evaluate the existing project documentation with + respect to the [project maturity level] or proposed maturity level, if the + analysis is associated with a project upgrade request. Identify gaps with + CNCF [criteria]. Write general recommendations to close the largest and most + important identified issues. +2. Write a implementation plan: decompose recommendations in to specific improvement suggestions. These can be additions or revisions to the docs; reorganization; website infrastructure changes; or any other work that will - close the gaps. Make suggestions specific (if you propose reorganizing a - section, for example, provide an outline) but provide enough information that - a contributor could solve the problem differently if they have a different - idea (make it clear that your proposed outline is only one possible - reorganization, e.g.). -3. Write the issue backlog. + close address issues. Make suggestions specific enough (for example, if you + propose reorganizing a section then provide an outline) without being overly + constraining so that a contributor could solve the problem differently if + they have a different solution. For example, make it clear that your proposed + outline is only one possible reorganization. +3. Write an issue backlog. -Finally, there are follow-up steps including creating GitHub issues and a pull -request, and getting approval from project maintainers. +Finally, there are follow-up steps including: + +- Creating GitHub issues and a pull request +- Getting approval from project maintainers ### Prerequisites -This process assumes you have some familiarity with GitHub repositories and pull -requests (PRs). +This section assumes you are familiar with GitHub repositories and pull requests +(PRs). If you need a refresher, see +[Get started](https://docs.github.com/en/get-started) from the GitHub docs. + +Project analyses are kept in the +[CNCF tech docs repository](https://github.com/cncf/techdocs). Clone and prepare +for 1. Clone the [CNCF tech docs repository](https://github.com/cncf/techdocs). -1. Create a branch for the analysis. -1. In the new branch, create a directory for the analysis in the CNCF tech docs - /analysis directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the +2. Create a branch for the analysis. +3. In the new branch, create a directory for the analysis in the CNCF tech docs + [analyses] directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the 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_. -1. Copy and rename the analysis doc templates from the - `/analysis/analysis-tools` directory as follows: `analysis-template.md` > - `_PROJECT_-analysis.md`; `implementation-template.md` > - `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` > - `_PROJECT_-issues.md`. +4. Copy all the doc analysis [templates]. ### Writing the Analysis document -Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step, -the analysis: +Follow the steps outlined below as a part of writing the project's analysis +document. Record your findings in the project's +[analysis.md](./templates/analysis.md) file. -1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs - and repositories included and excluded from the analysis. -1. Review the in-scope URLs and repositories for compliance with the rubric +1. Define the **scope** of the analysis. Edit "Scope of analysis" to reflect + URLs and repositories included and excluded from the analysis. +2. Review the in-scope URLs and repositories for compliance with the rubric criteria. Note any gaps, as well as any areas that exceed criteria or are exceptionally well executed. I find it easiest to do this separately for each of the three areas of concern (project doc, contributor doc, website), making @@ -81,11 +84,11 @@ the analysis: level (or proposed maturity level, if the analysis is part of a petition for upgrade). Write comments to note the most important gaps and best-executed features of the documentation. -1. Assign ratings to each criterion based on your comments and compliance with +3. Assign ratings to each criterion based on your comments and compliance with the maturity level expectations in the rubric. The ratings are self-explanatory. Keep in mind that "needs improvement" or "meets standards" is with respect to the current (or proposed) maturity level. -1. Write recommendations. The template implies that you'll do this for every +4. Write recommendations. The template implies that you'll do this for every criterion; the "Recommendations" headings mirror the "Comments" headings. However, if some alternative framework makes more sense, use that. For example, it might be that two or three of the product documentation criteria @@ -205,7 +208,14 @@ interested parties to get feedback on the analysis and implementation plan. ### Creating GitHub issues -Enter the backlog issues from the issues document into the project documentation -GitHub repository using the format in the umbrella-issues-template.md and -issues-template.md files. Create one GitHub issue per backlog issue, and create -an umbrella issue that contains a checklist item for each issue. +Create issues in the project documentation GitHub repository for: + +- Each issues in the [issues list]. +- An umbrella issue that provides a context for the previously created + individual issues. + +[analyses]: ../../analyses/ +[criteria]: ./criteria.md +[project maturity level]: https://www.cncf.io/project-metrics +[templates]: ./templates/ +[issues list]: ./templates/issues-list.md diff --git a/docs/analysis/templates/README.md b/docs/analysis/templates/README.md index 18aa6a6..164e410 100644 --- a/docs/analysis/templates/README.md +++ b/docs/analysis/templates/README.md @@ -1,6 +1,6 @@ # TechDoc Analysis Templates -This directory contains templates for analyzing a CNCF project's documentation. +This section contains templates for analyzing a CNCF project's documentation. Use the templates in this directory to perform a documentation analysis for CNCF. These materials provide: @@ -12,6 +12,5 @@ CNCF. These materials provide: - Emphasis on effective documentation that serves all users associated with the project. -Resources for completing a documentation analysis, including a -[how-to](../howto.md) guide and analysis [criteria](../criteria.md), are in the -`docs` directory. +For guidance in completing a documentation analysis, see +[Analysis how-to](../howto.md) and [criteria](../criteria.md) pages. diff --git a/docs/analysis/templates/analysis.md b/docs/analysis/templates/analysis.md index f769ff5..a7c1b2d 100644 --- a/docs/analysis/templates/analysis.md +++ b/docs/analysis/templates/analysis.md @@ -6,22 +6,31 @@ modified: YYYY-MM-DD author: _NAME_ (@_HANDLE_) --- - -See howto.md for a discussion of the analysis procedure. +## About this template ---> +TO USE THIS TEMPLATE, search and replace the named IDs: -# Introduction +- `_PROJECT_`: project name +- `YYYY-MM-DD`: creation and modification dates of the analysis document +- `_NAME_`: name of the analysis author +- `@_HANDLE_`: GitHub handle of the analysis author +- `_PROJECT-WEBSITE_`: landing page of the project's information website +- `_PROJECT-DOC-URL_`: main page of the technical documentation for the current + project revision; this might be on the main website server, for example as + _PROJECT-WEBSITE_/doc +- `_PROJECT-DOC-REPO_`: repository where the project technical documentation is + stored; this might be its own repo or a directory in the project main repo -This document analyzes the effectiveness and completeness of the +For the analysis procedure, see [Analysis how-to](../howto.md). + +> Note: delete this "About this template" section after you have customized this +> template for a specific project. + +## Introduction + +This document is an analyzes the effectiveness and completeness of the [_PROJECT_][project-website] open source software (OSS) project's documentation and website. It is funded by the CNCF Foundation as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. @@ -31,15 +40,14 @@ prerequisite for program graduation. The documentation analysis is the first step of a CNCF process aimed at assisting projects with their documentation efforts. -## Purpose +### Purpose 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 document, -`_PROJECT_-impementation.md`, outlines an actionable plan for improvement. A -third document, `_PROJECT_-issues.md`, enumerates a backlog 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 [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. This document: @@ -47,7 +55,7 @@ This document: - Compares existing documentation against the CNCF’s standards - Recommends a program of key improvements with the largest return on investment -## Scope of analysis +### Scope of analysis The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the @@ -59,19 +67,19 @@ Sphynx, other] static site generator with the [Docsy, other] theme and served fr [the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. -**In scope:** +#### 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]_ -**Out of scope:** +#### Out of scope - Other _PROJECT_ repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ -## How this document is organized +### How this document is organized This document is divided into three sections that represent three major areas of concern: @@ -84,38 +92,36 @@ concern: includes branding, website structure, and maintainability Each section begins with summary ratings based on a rubric with appropriate -[criteria][criteria-doc] for the section, then proceeds to: +[criteria] for the section, then proceeds to: - **Comments**: observations about the existing documentation, with a focus on how it does or does not help _PROJECT_ users achieve their goals. - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -An accompanying document, [`_PROJECT_-implementation.md`][implementation-doc], -breaks the recommendations down into concrete actions that can be implemented by -project contributors. Its focus is on drilling down to specific, achievable work -that can be completed in constrained blocks of time. Ultimately, the -implementation items are decomposed into a series of [issues][issues-doc] and -entered as GitHub [issues][project-doc-website]/issues. +The accompanying [implementation] document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. Ultimately, the implementation items are decomposed +into a series of [issues] and entered as GitHub [project-doc-website]/issues. -## How to use this document +### How to use this document Readers interested only in actionable improvements should skip this document and -read the [implementation plan][implementation-doc] and [issues -list][issues-doc]. +read the **[implementation] plan** and **[issues] list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation][project-heading] -- [Contributor documentation][contributor-heading] -- [Website and documentation infrastructure][website-heading] +- [Project documentation](?TODO=ADD-URL) +- [Contributor documentation](?TODO=ADD-URL) +- [Website and documentation infrastructure](?TODO=ADD-URL) Examples of CNCF documentation that demonstrate the analysis criteria are linked -from the [criteria][criteria-doc] specification. +from the [criteria] specification. -### Recommendations, requirements, and best practices +#### Recommendations, requirements, and best practices This analysis measures documentation against CNCF project maturity standards, and suggests possible improvements. In most cases there is more than one way to @@ -127,47 +133,39 @@ 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. -# Project documentation +## Project documentation - +> AUTHOR NOTE: Pick the CNCF maturity level of the project: _PROJECT_ is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria-doc] standards for documentation. +have [_very high_][criteria] standards for documentation. - +> AUTHOR NOTE: or _PROJECT_ is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria-doc] professional-quality documentation -alongside the project code. +should be [_developing_][criteria] professional-quality documentation alongside +the project code. -| Criterion | Rating (1-5) | +| Criterion | [Rating (1-5)] | | -------------------------- | -------------- | -| Information architecture | (rating value) | -| New user content | (rating value) | -| Content maintainability | (rating value) | -| Content creation processes | (rating value) | -| Inclusive language | (rating value) | - - - -## Comments - - +| Information architecture | [rating (1-5)] | +| New user content | [rating (1-5)] | +| Content maintainability | [rating (1-5)] | +| Content creation processes | [rating (1-5)] | +| Inclusive language | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Project Documentation here. The following sections contain brief assessments of each element of the Project Documentation rubric. - +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items, and +> especially the technical documentation, meet these criteria. (Criteria are +> copied from criteria.md) -### Information architecture +#### Information architecture The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: @@ -186,7 +184,7 @@ documentation. We evaluate on the following: - If the product exposes an API, is there a complete reference? - Is content up to date and accurate? -### New user content +#### New user content New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: @@ -200,7 +198,7 @@ specifically for them. We evaluate on the following: top of your information architecture? - Is there easily copy-pastable sample code or other example content? -### Content maintainability & site mechanics +#### Content maintainability & site mechanics As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. @@ -212,7 +210,7 @@ We evaluate on the following: directory structure? Is a localization framework present? - Do you have a clearly documented method for versioning your content? -### Content creation processes +#### Content creation processes Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. @@ -225,7 +223,7 @@ We evaluate on the following: - Who reviews and approves documentation pull requests? - Does the website have a clear owner/maintainer? -### Inclusive language +#### Inclusive language Creating inclusive project communities is a key goal for all CNCF projects. @@ -236,60 +234,55 @@ We evaluate on the following: [Inclusive Naming Initiative](https://inclusivenaming.org) website? - Does the project use language like "simple", "easy", etc.? -## Recommendations +### Recommendations - +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. -### Information architecture +#### Information architecture -### New user content +#### New user content -### Content maintainability & site mechanics +#### Content maintainability & site mechanics -### Content creation processes +#### Content creation processes -### Inclusive language +#### Inclusive language -# Contributor documentation +## Contributor documentation - +> AUTHOR NOTE: Pick the CNCF maturity level of the project: _PROJECT_ is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria-doc] standards for documentation. +have [_very high_][criteria] standards for documentation. - +> AUTHOR NOTE: or _PROJECT_ is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria-doc] professional-quality documentation -alongside the project code. +should be [_developing_][criteria] professional-quality documentation alongside +the project code. -| Criterion | Rating (1-5) | +| Criterion | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | (rating value) | -| Beginner friendly issue backlog | (rating value) | -| “New contributor” getting started content | (rating value) | -| Project governance documentation | (rating value) | - - +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | -## Comments +### Comments - +> AUTHOR NOTE: make any overall comments about the Contributor Documentation +> here. The following sections contain brief assessments of each element of the Contributor Documentation rubric. - +> AUTHOR NOTE: For each heading below, discuss how well the in-scope items meet +> these criteria. Keep in mind that much of the contributor documentation might +> be contained in the documentation repository. (Criteria are copied from +> criteria.md) -### Communication methods documented +#### Communication methods documented One of the easiest ways to attract new contributors is making sure they know how to reach you. @@ -303,7 +296,7 @@ We evaluate on the following: join those meetings? - Are mailing lists documented? -### Beginner friendly issue backlog +#### Beginner friendly issue backlog We evaluate on the following: @@ -313,7 +306,7 @@ We evaluate on the following: - Are issues well-documented (i.e., more than just a title)? - Are issues maintained for staleness? -### New contributor getting started content +#### New contributor getting started content Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump @@ -325,7 +318,7 @@ We evaluate on the following: - Is there a document specifically for new contributors/your first contribution? - Do new users know where to get help? -### Project governance documentation +#### Project governance documentation One of the CNCF’s core project values is open governance. @@ -333,68 +326,65 @@ We evaluate on the following: - Is project governance clearly documented? -## Recommendations +### Recommendations - +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. -### Communication methods documented +#### Communication methods documented -### Beginner friendly issue backlog +#### Beginner friendly issue backlog -### New contributor getting started content +#### New contributor getting started content -### Project governance documentation +#### Project governance documentation -# Website and infrastructure +## Website and infrastructure - +> AUTHOR NOTE: Pick the CNCF maturity level of the project: _PROJECT_ is a **graduated** project of CNCF. This means that the project should -have [_very high_][criteria-doc] standards for documentation. +have [_very high_][criteria] standards for documentation. - +> AUTHOR NOTE: or _PROJECT_ is an **incubating** project of CNCF. This means that the project -should be [_developing_][criteria-doc] professional-quality documentation -alongside the project code. +should be [_developing_][criteria] professional-quality documentation alongside +the project code. -| Criterion | Rating (1-5) | +| Criterion | [Rating (1-5)] | | ------------------------------------------- | -------------- | -| Single-source for all files | (rating value) | -| Meets min website req. (for maturity level) | (rating value) | -| Usability, accessibility, and design | (rating value) | -| Branding and design | (rating value) | -| Case studies/social proof | (rating value) | -| SEO, Analytics, and site-local search | (rating value) | -| Maintenance planning | (rating value) | -| A11y plan & implementation | (rating value) | -| Mobile-first plan & impl. | (rating value) | -| HTTPS access & HTTP redirect | (rating value) | -| Google Analytics 4 for production only | (rating value) | -| Indexing allowed for production server only | (rating value) | -| Intra-site / local search | (rating value) | -| Account custodians are documented | (rating value) | - - - -## Comments - - +| Single-source for all files | [rating (1-5)] | +| Meets min website req. (for maturity level) | [rating (1-5)] | +| Usability, accessibility, and design | [rating (1-5)] | +| Branding and design | [rating (1-5)] | +| Case studies/social proof | [rating (1-5)] | +| SEO, Analytics, and site-local search | [rating (1-5)] | +| Maintenance planning | [rating (1-5)] | +| A11y plan & implementation | [rating (1-5)] | +| Mobile-first plan & impl. | [rating (1-5)] | +| HTTPS access & HTTP redirect | [rating (1-5)] | +| Google Analytics 4 for production only | [rating (1-5)] | +| Indexing allowed for production server only | [rating (1-5)] | +| Intra-site / local search | [rating (1-5)] | +| Account custodians are documented | [rating (1-5)] | + +### Comments + +> AUTHOR NOTE: make any overall comments about the Website and documentation +> infrastructure here. The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. - +> AUTHOR NOTE: for each heading below, discuss how well the in-scope items meet +> 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 +> criteria.md) -### Single-source requirement +#### Single-source requirement Source files for _all website pages_ should reside in a single repo. Among other problems, keeping source files in two places: @@ -411,27 +401,30 @@ submodules][git-submodules]. If a project chooses to keep source files in multiple repos, they need a clearly documented strategy for managing mirrored files and new contributions. -### Minimal website requirements +#### Minimal website requirements Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) -| Criterion | Incubating Requirement | Graduated Requirement | -| ---------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | -| [Website guidelines][website-guidelines] | All guidelines satisfied | All guidelines satisfied | -| [Docs analysis][analysis-doc] (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | -| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | -| **Project doc**: hosting | Hosted directly | Hosted directly | -| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + +| Criterion | Incubating Requirement | Graduated Requirement | +| ----------------------------- | ------------------------------------------------------- | ----------------------------------------- | +| [Website guidelines] | All guidelines satisfied | All guidelines satisfied | +| **Docs analysis** (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | +| **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | +| **Project doc**: hosting | Hosted directly | Hosted directly | +| **Project doc**: user docs | Comprehensive, addressing most stakeholder needs | Fully addresses needs of key stakeholders | + + [git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[website-guidelines]: ../../website-guidelines-checklist.md [maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io -### Usability, accessibility and devices +#### Usability, accessibility and devices Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will @@ -456,7 +449,7 @@ It is up to each project to set their own guidelines. [accessibility]: https://developer.mozilla.org/en-US/docs/Web/Accessibility -### Branding and design +#### Branding and design CNCF seeks to support enterprise-ready open source software. A key aspect of this is branding and marketing. @@ -468,7 +461,7 @@ We evaluate on the following: - Is the brand used across the website consistently? - Is the website’s typography clean and well-suited for reading? -### Case studies/social proof +#### Case studies/social proof One of the best ways to advertise an open source project is to show other organizations using it. @@ -482,7 +475,7 @@ We evaluate on the following: - Are there community talks for the project and are they present on the website? - Is there a logo wall of users/participating organizations? -### SEO, Analytics and site-local search +#### SEO, Analytics and site-local search SEO helps users find your project and it's documentation, and analytics helps you monitor site traffic and diagnose issues like page 404s. Intra-site search, @@ -502,7 +495,7 @@ We evaluate on the following: - Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) -### Maintenance planning +#### Maintenance planning Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. @@ -515,43 +508,49 @@ We evaluate on the following: - Are site build times reasonable? - Do site maintainers have adequate permissions? -### Other +#### Other - Is your website accessible via HTTPS? - Does HTTP access, if any, redirect to HTTPS? -## Recommendations +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Single-source requirement + +#### Minimal website requirements - +#### Usability, accessibility and devices -### Single-source requirement +#### Branding and design -### Minimal website requirements +#### Case studies/social proof -### Usability, accessibility and devices +#### SEO, Analytics and site-local search -### Branding and design +#### Maintenance planning -### Case studies/social proof +#### Other -### SEO, Analytics and site-local search +#### References and notes -### Maintenance planning +##### Rating values -### Other +The numeric rating values used in this document are as follows - +1. Not present +2. Needs improvement +3. Meets standards +4. Meets or exceeds standards +5. Exemplary -[project-website]: #?_PROJECT-WEBSITE_ -[project-doc-website]: #?_PROJECT-DOC-URL_ -[criteria-doc]: ../criteria.md -[implementation-template]: ./implementation.md -[issues-template]: ./issue-template.md -[umbrella-template]: ./umbrella-issue.md -[implementation-doc]: #?_PROJECT_-implementation.md -[issues-doc]: #?_PROJECT_-issues.md -[project-heading]: #project-documentation -[contributor-heading]: #contributor-documentation -[website-heading]: #website +[criteria]: ../criteria.md +[implementation]: ./implementation.md +[issues list]: ./issues-list.md +[project-doc-website]: ?_PROJECT-DOC-URL_ +[project-website]: ?_PROJECT-WEBSITE_ +[Rating (1-5)]: #rating-values [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 -[website-guidelines]: ../../website-guidelines-checklist.md +[website guidelines]: ../../website-guidelines-checklist.md diff --git a/docs/analysis/templates/implementation.md b/docs/analysis/templates/implementation.md index a32927e..0c89420 100644 --- a/docs/analysis/templates/implementation.md +++ b/docs/analysis/templates/implementation.md @@ -3,15 +3,17 @@ title: Implementing _PROJECT_ Doc Improvements tags: _PROJECT_ --- -# Introduction + + +## Introduction This document provides actionable suggestions for improving the _PROJECT_ technical documentation. For an analysis and general discussion of recommendations on _PROJECT_ technical -documentation, see [_PROJECT_-analysis.md][]. +documentation, see [analysis.md](analysis.md). -## Recommendations, requirements, and best practices +### Recommendations, requirements, and best practices This analysis measures documentation against CNCF project maturity standards and suggests possible improvements. In most cases there is more than one way to do @@ -26,20 +28,22 @@ such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - - -# High-level action 1 +> AUTHOR NOTE: Provide a summary or outline of the recommendations. Depending on +> the analysis findings, recommended actions might be organized into two or +> three high-level items that contain multiple actions, or might just be a list +> of independent changes. For examples, see a completed implementation plan such +> as 0008-Backstage or 0010-etcd. -## Issue 1 +## High-level action 1 -## Issue 2 +### Issue 1 -# High-level action 2 +### Issue 2 -## Issue 1 +## High-level action 2 -## Issue 2 +### Issue 1 - +### Issue 2 [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/docs/analysis/templates/issue.md b/docs/analysis/templates/issue.md index 4dbcbba..a1d81d0 100644 --- a/docs/analysis/templates/issue.md +++ b/docs/analysis/templates/issue.md @@ -3,39 +3,53 @@ title: _PROJECT_ Issue tags: _PROJECT_ --- - +> AUTHOR NOTE: This template provides one possible format for the individual +> issues filed in the Issues of a project repository. Within the CNCF tech docs +> repo, include all issues in one document, `_PROJECT_-issues.md`. See any +> completed analysis for an example. -# Overview +## Overview - +> AUTHOR NOTE: +> +> - Summarize the documentation changes prescribed by this issue. +> - For the audience, provide the user role to which the issue is most +> applicable. -Audience: +Audience: Type: - +> AUTHOR NOTE: What type of documentation topic the change affects. One of Task, +> Reference, or Conceptual. -# Context +## Context - +> AUTHOR NOTE: This is boilerplate text linking back to the doc analysis. This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are here: under `00NN-project`. -# Possible Implementation +## Possible Implementation - +> AUTHOR NOTE: Include a bullet list of links to pages that are affected by the +> change: Related material in the current doc: - For example, `https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials` - +> AUTHOR NOTE: Describe in detail a suggested way to achieve the goals of the +> issue. This should be specific enough to provide a contributor with a recipe +> for making the change; however, the contributor should feel free to solve the +> problem differently if they have an idea how it should be done. +> +> An EXAMPLE is provided next. -Suggested changes: +Suggested changes: Use the following outline to write a procedure for each task: diff --git a/docs/analysis/templates/issues-list.md b/docs/analysis/templates/issues-list.md new file mode 100644 index 0000000..49c8742 --- /dev/null +++ b/docs/analysis/templates/issues-list.md @@ -0,0 +1,52 @@ +--- +title: _PROJECT_ Umbrella Issue and Issues List +tags: _PROJECT_ +--- + +## Overview + +> AUTHOR NOTES: +> +> - Provide an outline or high-level description of the recommended changes. +> Note any general patterns that occur throughout the documentation, such as a +> lack of step-by-step procedures. +> +> -Items might be disjoint and unrelated; that's OK. If there are high-level +> items that must be broken down into smaller issues, use the high-level items +> to organize the issues in this plan. Otherwise, list issues in order from the +> analysis document. This is an improvement plan, not a legal brief. +> +> - The following is boilerplate language to include in the umbrella issue in +> the repo: + +This issue tracks recommended changes resulting from an analysis of the +_PROJECT_ documentation commissioned by CNCF. The analysis and supporting +documents are here: under +`00NN-project`. + +The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: + + +## Umbrella issue + +> AUTHOR NOTE: Link to the umbrella issue in the project's documentation repo + +## Issues + +This is a list of issues representing the recommended work on the _PROJECT_ +website and technical documentation. + +> AUTHOR NOTE: Consider using the [issue](issue.md) template. + +### Issue: Item 1 + +> AUTHOR NOTE: Summarize the documentation changes prescribed by this issue. Use +> enough detail to estimate the scope of the issue. Fine-grained detail can go +> in the issue itself. In the GitHub umbrella issue, link to the sub-issue using +> a Markdown checkbox as shown below. + +- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` + +### Issue: Item 2 + +> AUTHOR NOTE: ... and so on. diff --git a/docs/analysis/templates/umbrella-issue.md b/docs/analysis/templates/umbrella-issue.md deleted file mode 100644 index 7e44352..0000000 --- a/docs/analysis/templates/umbrella-issue.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: _PROJECT_ Umbrella Issue -tags: _PROJECT_ ---- - -# Overview - - - - - - - -This issue tracks recommended changes resulting from an analysis of the -_PROJECT_ documentation commissioned by CNCF. The analysis and supporting -documents are here: under -`00NN-project`. - -The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo: - - -# Issues - -This is a list of issues representing the recommended work on the _PROJECT_ -website and technical documentation. - -## Issue: Item 1 - - - -- [ ] `https://github.com/_PROJECT_/repo/issues/NNN` - -## Issue: Item 2 - - diff --git a/docs/analytics.md b/docs/analytics.md index 460b116..3836b97 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -32,22 +32,22 @@ 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. - -2. Determine which **analytics library** your project's website is using. - - - Visit your project's website. - - View the page source of any website page. - - Search for "`https://www.google`". Look at all instances. - - If one of the matching URLs ends with: - - [analytics.js][], then your site is using the older (pre 2017) analytics - library. - - [gtag.js][], then your site is using the library that supports both UA - and GA4 tags. - - Take note of which library or libraries (some sites use both) your site is - using. +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. + +2. Determine which **analytics library** your project's website is using. + + - Visit your project's website. + - View the page source of any website page. + - Search for "`https://www.google`". Look at all instances. + - If one of the matching URLs ends with: + - [analytics.js][], then your site is using the older (pre 2017) analytics + library. + - [gtag.js][], then your site is using the library that supports both UA + and GA4 tags. + - Take note of which library or libraries (some sites use both) your site is + using. ### Stage 1 - create a GA4 site tag @@ -95,8 +95,8 @@ Follow these steps: site tag. Perform the remaining steps from your GA4 console. - Select **Admin** > **Data stream** - Select the (only) data stream to view its details. - - 📋 **Copy the **measurement ID\*\*\*\*, you'll need it later, and paste it - into the appropriate row of the [status table][]. + - 📋 **Copy the _measurement ID_**, you'll need it later, and paste it into + the appropriate row of the [status table][]. 5. Rename your UA property by adding the `- UA` suffix. From the UA console: @@ -189,7 +189,6 @@ is using. https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics [analytics.js]: https://support.google.com/analytics/answer/10268458 [connected]: https://support.google.com/analytics/answer/9973999 -[etcd.io issue #595]: https://github.com/etcd-io/website/issues/595 [docsy]: https://www.docsy.dev [docusaurus]: https://docusaurus.io/ [ga4-dev]: https://developers.google.com/analytics/devguides/migration @@ -199,8 +198,6 @@ is using. [gtag.js]: https://support.google.com/analytics/answer/10220869 [issue #108]: https://github.com/cncf/techdocs/issues/108 [migration-help]: https://support.google.com/analytics/answer/10759417 -[opentelemetry.io/layouts/partials/google-analytics.html]: - https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html [stage 2]: #stage-2---configure-the-ga4-id-as-the-main-analytics-id [status table]: https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA diff --git a/docs/repo-setup.md b/docs/repo-setup.md index d437e58..e70a460 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -29,38 +29,35 @@ For documentation this means you must: 1. Add copyright notices for both the code and the docs to the repository's `README` and the website's footer -For the repository: + For the repository: -``` -# License + ```markdown + # License -$PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE). + $PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE). -The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](./LICENSE-docs). -``` + The #PROJECT_NAME documentation is licensed under a + [CC-BY-4.0 license](./LICENSE-docs). + ``` -For the footer: - -- [`cncf/hugo-netlify-starter`](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html) - contains a basic implementation, where the year and project name are - parameterized. + For the footer, see + [cncf/hugo-netlify-starter](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html) + contains a basic implementation, where the year and project name are + parameterized. 2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the - root directory of the documentation - - Plain text versions of both - [here](https://github.com/cncf/project-template) + root directory of the documentation. For a plain text versions of both, see + [cncf/project-template](https://github.com/cncf/project-template) -For more information: +For more information, see: -- Read - [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md) -- And the - [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) +- [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md) +- [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) ## README All docs repositories should have a README file that includes build instructions. Look at [Longhorn's](https://github.com/longhorn/website) for an example, and the -[`cncf/project-template`](https://github.com/cncf/project-template) for +[cncf/project-template](https://github.com/cncf/project-template) for boilerplate. diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md index 18e411b..cc96298 100644 --- a/docs/searching-documentation.md +++ b/docs/searching-documentation.md @@ -1,5 +1,7 @@ # Documentation Search + + This page describes some common alternatives for static site search. - [Google search](#programmable-search-engine-by-google) diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 02e81ea..df115b4 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -1,5 +1,7 @@ # Technical Documentation Versioning with Hugo & Netlify + + Technical Documents Versioning is an intersection of: **Changes** + **Language** + **Navigation** + **Search** @@ -78,7 +80,7 @@ site. Each version of the documentation is placed in its own folder. This is probably the easiest way to start versioning. -``` +```text content └── docs ├── _index.md @@ -160,8 +162,7 @@ Scores high on: Same style of dropdown function as above, but made simpler because of the configuration: - -https://kubernetes.io `website/layouts/partials/navbar-version-selector.html` + ```html
[4](#footnote4) The dropdown example is made simpler because the config is more complex and because the server setup is more complex. -https://kubernetes.io `website/config.toml` + ```toml [[params.versions]] diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 1455e21..e8b8ace 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -7,9 +7,8 @@ all projects - [ ] 1. Website should be [hosted in an open source repo](./repo-setup.md) - [ ] Hosted in the same organization as the main project - - [ ] Setup [DCO](https://github.com/apps/dco) or CLA (DCO recommended) - CNCF's IP policy - (https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) + - [ ] Setup [DCO](https://github.com/apps/dco) or CLA (DCO recommended) + [CNCF's IP policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) requires all projects to use either CLA (Contributor License Agreements) or [DCO (Developer Certificate of Origin)](https://github.com/apps/dco). Unless there's a strong necessity to use CLA, we encourage projects to diff --git a/package.json b/package.json index a57f3ae..a20b62a 100644 --- a/package.json +++ b/package.json @@ -4,11 +4,17 @@ "description": "Resources provided by the CNCF Technical Documentation team.", "scripts": { "_check:format:any": "npx prettier --check --ignore-path ''", + "_check:format:delta": "npx prettier --check --ignore-path '' `git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)'`", "_check:format": "npx prettier --check .", + "_check:links": "npx markdown-link-check --config .markdown-link-check.json", + "_check:markdown:all": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/00(0\\d|10|11)-' | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", + "_check:markdown:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$' | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}", + "_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml", "_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: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", @@ -21,10 +27,12 @@ "devDependencies": { "cspell": "^8.8.4", "markdown-link-check": "^3.12.2", - "prettier": "^3.3.1" + "markdownlint": "^0.34.0", + "markdownlint-cli": "^0.41.0", + "prettier": "^3.3.2" }, "private": true, - "spelling": "cSpell:ignore loglevel -", + "spelling": "cSpell:ignore ACMR loglevel -", "prettier": { "proseWrap": "always", "singleQuote": true