mirror of https://github.com/cncf/techdocs.git
[CI & docs] Rework of analysis docs + improved checks (#256)
This commit is contained in:
Patrice Chalin
GitHub
parent
64a4d8a299
commit
a15161f612
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
15
README.md
15
README.md
|
|
@ -13,27 +13,29 @@ team. The repo contains the following directories:
|
|||
|
||||
The full-time staff of the CNCF Tech Docs team is:
|
||||
|
||||
<!-- markdownlint-disable line-length -->
|
||||
|
||||
| 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 |
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
<!-- cSpell:ignore chalin nate thisisobate -->
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ documentation. We evaluate on the following:
|
|||
|
||||
Examples:
|
||||
|
||||
- https://prometheus.io/docs/
|
||||
- <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/
|
||||
- <https://falco.org/docs/getting-started/>
|
||||
|
||||
### Content maintainability & site mechanics
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ We evaluate on the following:
|
|||
|
||||
Examples:
|
||||
|
||||
- https://kubernetes.io/docs/
|
||||
- <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
|
||||
- <https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md> (clearly
|
||||
documented maintainers)
|
||||
- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md
|
||||
- <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/
|
||||
- <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
|
||||
- <https://github.com/opentracing/opentracing.io/issues> (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
|
||||
- <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/
|
||||
- <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)
|
||||
- <https://www.fluentd.org/testimonials> (user testimonials)
|
||||
- <https://goharbor.io/> (logo wall)
|
||||
- <https://blog.rook.io/> (blog)
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
|
||||
|
|
@ -314,7 +315,7 @@ We evaluate on the following:
|
|||
|
||||
Examples:
|
||||
|
||||
- http://kubernetes.io
|
||||
- <https://kubernetes.io>
|
||||
|
||||
### Other
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -6,22 +6,31 @@ modified: YYYY-MM-DD
|
|||
author: _NAME_ (@_HANDLE_)
|
||||
---
|
||||
|
||||
<!-- TO USE THIS TEMPLATE: Search and replace:
|
||||
_PROJECT_ with the project name
|
||||
YYYY-MM-DD with the creation and modification dates of the analysis document
|
||||
_NAME_ with the name of the analysis author
|
||||
@_HANDLE_ with the GitHub handle of the analysis author
|
||||
_PROJECT-WEBSITE_ with the landing page of the project's information website
|
||||
_PROJECT-DOC-URL_ with the 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_ with the repository where the project technical documentation is stored; this might be its own repo or a directory in the project main repo
|
||||
<!-- markdownlint-disable no-duplicate-heading -->
|
||||
|
||||
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
|
||||
|
||||
<!-- Pick the CNCF maturity level of the project: -->
|
||||
> 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.
|
||||
|
||||
<!-- or -->
|
||||
> 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) |
|
||||
| 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)] |
|
||||
|
||||
<!-- Rating values:
|
||||
1 - not present
|
||||
2 - needs improvement
|
||||
3 - meets standards
|
||||
4 - meets or exceeds standards
|
||||
5 - exemplary
|
||||
-->
|
||||
### Comments
|
||||
|
||||
## Comments
|
||||
|
||||
<!--
|
||||
Make any overall comments about the Project Documentation here.
|
||||
-->
|
||||
> 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.
|
||||
|
||||
<!-- 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) -->
|
||||
> 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
|
||||
|
||||
<!-- Write general recommendations based on the comments from the previous section. -->
|
||||
> 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
|
||||
|
||||
<!-- Pick the CNCF maturity level of the project: -->
|
||||
> 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.
|
||||
|
||||
<!-- or -->
|
||||
> 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)] |
|
||||
|
||||
<!-- Rating values:
|
||||
1 - not present
|
||||
2 - needs improvement
|
||||
3 - meets standards
|
||||
4 - meets or exceeds standards
|
||||
5 - exemplary
|
||||
-->
|
||||
### Comments
|
||||
|
||||
## Comments
|
||||
|
||||
<!--
|
||||
Make any overall comments about the Contributor Documentation here.
|
||||
-->
|
||||
> 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.
|
||||
|
||||
<!-- 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) -->
|
||||
> 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
|
||||
|
||||
<!-- Write general recommendations based on the comments from the previous section. -->
|
||||
> 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
|
||||
|
||||
<!-- Pick the CNCF maturity level of the project: -->
|
||||
> 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.
|
||||
|
||||
<!-- or -->
|
||||
> 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) |
|
||||
| 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)] |
|
||||
|
||||
<!-- Rating values:
|
||||
1 - not present
|
||||
2 - needs improvement
|
||||
3 - meets standards
|
||||
4 - meets or exceeds standards
|
||||
5 - exemplary
|
||||
-->
|
||||
### Comments
|
||||
|
||||
## Comments
|
||||
|
||||
<!--
|
||||
Make any overall comments about the Website and documentation infrastructure here.
|
||||
-->
|
||||
> 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.
|
||||
|
||||
<!-- 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) -->
|
||||
> 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 |
|
||||
<!-- markdownlint-disable line-length -->
|
||||
|
||||
| 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 |
|
||||
|
||||
<!-- markdownlint-enable line-length -->
|
||||
|
||||
[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
|
||||
|
||||
<!-- Write general recommendations based on the comments from the previous section. -->
|
||||
> AUTHOR NOTE: Write general recommendations based on the comments from the
|
||||
> previous section.
|
||||
|
||||
### Single-source requirement
|
||||
#### Single-source requirement
|
||||
|
||||
### Minimal website requirements
|
||||
#### Minimal website requirements
|
||||
|
||||
### Usability, accessibility and devices
|
||||
#### Usability, accessibility and devices
|
||||
|
||||
### Branding and design
|
||||
#### Branding and design
|
||||
|
||||
### Case studies/social proof
|
||||
#### Case studies/social proof
|
||||
|
||||
### SEO, Analytics and site-local search
|
||||
#### SEO, Analytics and site-local search
|
||||
|
||||
### Maintenance planning
|
||||
#### Maintenance planning
|
||||
|
||||
### Other
|
||||
#### Other
|
||||
|
||||
<!--- References --->
|
||||
#### References and notes
|
||||
|
||||
[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
|
||||
##### Rating values
|
||||
|
||||
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
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -3,15 +3,17 @@ title: Implementing _PROJECT_ Doc Improvements
|
|||
tags: _PROJECT_
|
||||
---
|
||||
|
||||
# Introduction
|
||||
<!-- markdownlint-disable no-duplicate-heading -->
|
||||
|
||||
## 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:
|
||||
|
||||
<!-- 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. -->
|
||||
> 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.
|
||||
|
||||
# High-level action 1
|
||||
## High-level action 1
|
||||
|
||||
## Issue 1
|
||||
### Issue 1
|
||||
|
||||
## Issue 2
|
||||
### Issue 2
|
||||
|
||||
# High-level action 2
|
||||
## High-level action 2
|
||||
|
||||
## Issue 1
|
||||
### Issue 1
|
||||
|
||||
## Issue 2
|
||||
|
||||
<!--- References --->
|
||||
### Issue 2
|
||||
|
||||
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119
|
||||
|
|
|
|||
|
|
@ -3,39 +3,53 @@ title: _PROJECT_ Issue
|
|||
tags: _PROJECT_
|
||||
---
|
||||
|
||||
<!-- 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. -->
|
||||
> 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
|
||||
|
||||
<!-- Summarize the documentation changes prescribed by this issue. -->
|
||||
> 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: <!-- Provide the user role to which the issue is most applicable. -->
|
||||
Audience:
|
||||
|
||||
Type:
|
||||
|
||||
<!-- What type of documentation topic the change affects. One of Task, Reference, or Conceptual. -->
|
||||
> AUTHOR NOTE: What type of documentation topic the change affects. One of Task,
|
||||
> Reference, or Conceptual.
|
||||
|
||||
# Context
|
||||
## Context
|
||||
|
||||
<!-- This is boilerplate text linking back to the doc analysis. -->
|
||||
> 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: <https://github.com/cncf/techdocs/tree/main/analyses> under
|
||||
`00NN-project`.
|
||||
|
||||
# Possible Implementation
|
||||
## Possible Implementation
|
||||
|
||||
<!-- Include a bullet list of links to pages that are affected by the change: -->
|
||||
> 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`
|
||||
|
||||
<!-- 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. -->
|
||||
> 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: <!-- (example) -->
|
||||
Suggested changes:
|
||||
|
||||
Use the following outline to write a procedure for each task:
|
||||
|
||||
|
|
|
|||
|
|
@ -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: <https://github.com/cncf/techdocs/tree/main/analyses> under
|
||||
`00NN-project`.
|
||||
|
||||
The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
|
||||
<https://github.com/cncf/techdocs/issues>
|
||||
|
||||
## 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.
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
---
|
||||
title: _PROJECT_ Umbrella Issue
|
||||
tags: _PROJECT_
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
<!-- 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: <https://github.com/cncf/techdocs/tree/main/analyses> under
|
||||
`00NN-project`.
|
||||
|
||||
The CNCF _PROJECT_ documentation effort is tracked in the CNCF Tech Docs repo:
|
||||
<https://github.com/cncf/techdocs/issues>
|
||||
|
||||
# Issues
|
||||
|
||||
This is a list of issues representing the recommended work on the _PROJECT_
|
||||
website and technical documentation.
|
||||
|
||||
## Issue: Item 1
|
||||
|
||||
<!-- 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
|
||||
|
||||
<!-- ... and so on. -->
|
||||
|
|
@ -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.
|
||||
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.
|
||||
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.
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Documentation Search
|
||||
|
||||
<!-- markdownlint-disable no-duplicate-heading -->
|
||||
|
||||
This page describes some common alternatives for static site search.
|
||||
|
||||
- [Google search](#programmable-search-engine-by-google)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# Technical Documentation Versioning with Hugo & Netlify
|
||||
|
||||
<!-- markdownlint-disable no-emphasis-as-heading -->
|
||||
|
||||
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`
|
||||
<https://github.com/kubernetes/website/blob/main/layouts/partials/navbar-version-selector.html>
|
||||
|
||||
```html
|
||||
<div
|
||||
|
|
@ -181,7 +182,7 @@ Pursley et al. (2020, L4-L9)<sup>[4](#footnote4)</sup>
|
|||
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`
|
||||
<https://github.com/kubernetes/website/blob/main/hugo.toml>
|
||||
|
||||
```toml
|
||||
[[params.versions]]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
15
package.json
15
package.json
|
|
@ -4,11 +4,20 @@
|
|||
"description": "Resources provided by the CNCF Technical Documentation team.",
|
||||
"scripts": {
|
||||
"_check:format:any": "npx prettier --check --ignore-path ''",
|
||||
"_check:format:delta": "npm run _check:format:any -- $(npm run -s _list:git:delta)",
|
||||
"_check:format": "npx prettier --check .",
|
||||
"_check:links": "npx markdown-link-check --config .markdown-link-check.json",
|
||||
"_check:markdown:all": "npm run -s _list:check:md | xargs -I {} -P 4 npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
|
||||
"_check:markdown:delta": "npm run -s _list:git:delta | xargs -I {} npx -p markdownlint-cli markdownlint -c .markdownlint.yaml {}",
|
||||
"_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml",
|
||||
"_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'",
|
||||
"_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'",
|
||||
"_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010|/0011'",
|
||||
"_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 +30,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
|
||||
|
|
|
|||
Loading…
Reference in New Issue