mirror of https://github.com/cncf/techdocs.git
Criteria: sandbox update/clarification (#266)
* Update README.md Corrected with new directory structure. Reorganized description. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Updated sandbox website assessment requirement. Miscellaneous small corrections. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Fix formatting errors, primarily line legth/LINT. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Fix MD linter and line-length errors. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Trailing spaces? Really? Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-implementation.md Fixed faq link Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-issues.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting issues brought up by prettier Signed-off-by: Nate W <natew@cncf.io> * Update docs/analysis/criteria.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> * Update assistance.md Added a note to address program differences for projects at the Sandbox maturity level. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update assistance.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --------- Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W <natew@cncf.io> Co-authored-by: Nate W <natew@cncf.io>
This commit is contained in:
Dave Welsch
GitHub
parent
d144317fb6
commit
3959be809c
66
README.md
66
README.md
|
|
@ -3,11 +3,39 @@
|
|||
This repository holds resources provided by the CNCF Technical Documentation
|
||||
team. The repo contains the following directories:
|
||||
|
||||
- `analysis` contains instructions, templates, and criteria for requesting and
|
||||
performing an analysis of an OSS project's website and technical
|
||||
documentation. Completed analyses are stored here as well.
|
||||
- `resources` contains information that OSS teams can use to set up a
|
||||
documentation project as suggested by the TechDocs team.
|
||||
- `docs` contains collected resources for building websites and developing
|
||||
documentation, including recommended tools and practices, how-tos, and
|
||||
evaluation checklists. Included are specific guidelines for:
|
||||
- Setting up and maintaining a documentation website.
|
||||
- Writing technical documentation for a project.
|
||||
- Getting assistance from the CNCF TechDocs community.
|
||||
- Analyzing project documentation, for use by CNCF TechDocs staff (in
|
||||
`docs/analysis`).
|
||||
- `analyses` (not to be confused with `docs/analysis`) contains all the
|
||||
completed documentation analyses.
|
||||
|
||||
## TechDocs Q&A
|
||||
|
||||
The CNCF tech docs team holds a Zoom call to answer questions and discuss
|
||||
anything to do with documentation. Calls are held on the [fourth Wednesday of
|
||||
every month at 8am Pacific time][date-time].
|
||||
|
||||
TechDocs Q&A (formerly called _Office Hours_) started on 30 September 2020.
|
||||
|
||||
### Meeting link
|
||||
|
||||
- [Zoom meeting 95471930872]
|
||||
|
||||
### Meeting notes
|
||||
|
||||
We store ongoing meeting notes in a
|
||||
[Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/).
|
||||
|
||||
## Assistance program for technical documentation
|
||||
|
||||
The TechDocs team can help CNCF projects analyze and improve their
|
||||
documentation. For details, see the TechDocs
|
||||
[assistance program](docs/assistance.md).
|
||||
|
||||
## CNCF TechDocs team
|
||||
|
||||
|
|
@ -26,34 +54,6 @@ The full-time staff of the CNCF Tech Docs team is:
|
|||
|
||||
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][date-time].
|
||||
|
||||
Office hours started on 30 September 2020.
|
||||
|
||||
### Meeting link
|
||||
|
||||
- [Zoom meeting 95471930872]
|
||||
|
||||
### Meeting notes
|
||||
|
||||
We store ongoing meeting notes in a
|
||||
[Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/).
|
||||
|
||||
## Assistance program for technical documentation
|
||||
|
||||
The TechDocs team can assist CNCF projects analyze and improve their
|
||||
documentation. For details, see the TechDocs
|
||||
[assistance program](docs/assistance.md).
|
||||
|
||||
### Resources
|
||||
|
||||
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]:
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents:
|
|||
- [Events](https://keda.sh/docs/2.13/operate/events/)
|
||||
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
|
||||
- ...
|
||||
- [FAQ](https://keda.sh/docs/latest/faq/)
|
||||
- [FAQ](https://keda.sh/docs/2.13/reference/faq/)
|
||||
- Glossary
|
||||
- [Scalers](https://keda.sh/docs/2.13/scalers/)
|
||||
- [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/)
|
||||
|
|
|
|||
|
|
@ -180,7 +180,7 @@ or provide a starting point.
|
|||
- [Events](https://keda.sh/docs/2.13/operate/events/)
|
||||
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
|
||||
- ...
|
||||
- [FAQ](https://keda.sh/docs/latest/faq/)
|
||||
- [FAQ](https://keda.sh/docs/2.13/reference/faq/)
|
||||
- Glossary
|
||||
|
||||
# Separate reference and task information
|
||||
|
|
|
|||
|
|
@ -21,7 +21,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?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://prometheus.io/docs>
|
||||
|
||||
|
|
@ -39,7 +39,10 @@ specifically for them. We evaluate on the following:
|
|||
top of your information architecture?
|
||||
- Is there easily copy-pastable sample code or other example content?
|
||||
|
||||
Examples:
|
||||
<!-- markdownlint-enable line-length -->
|
||||
<!-- cSpell:ignore OSes copy-pastable Algolia Docsy -->
|
||||
|
||||
Example:
|
||||
|
||||
- <https://falco.org/docs/getting-started/>
|
||||
|
||||
|
|
@ -55,7 +58,7 @@ We evaluate on the following:
|
|||
directory structure? Is a localization framework present?
|
||||
- Do you have a clearly documented method for versioning your content?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://kubernetes.io/docs/>
|
||||
|
||||
|
|
@ -105,7 +108,7 @@ We evaluate on the following:
|
|||
join those meetings?
|
||||
- Are mailing lists documented?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://prometheus.io/community/>
|
||||
|
||||
|
|
@ -119,7 +122,7 @@ We evaluate on the following:
|
|||
- Are issues well-documented (i.e., more than just a title)?
|
||||
- Are issues maintained for staleness?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://github.com/opentracing/opentracing.io/issues> (all of open tracing’s
|
||||
backlogs are well maintained!)
|
||||
|
|
@ -136,7 +139,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?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://github.com/helm/community>
|
||||
|
||||
|
|
@ -148,9 +151,9 @@ We evaluate on the following:
|
|||
|
||||
- Is project governance clearly documented?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- Any graduated CNCF project
|
||||
- <https://github.com/envoyproxy/envoy/blob/main/GOVERNANCE.md>
|
||||
|
||||
## Website
|
||||
|
||||
|
|
@ -181,16 +184,20 @@ maturity levels so, for example, incubating projects must satisfy the
|
|||
requirements for sandbox projects.
|
||||
|
||||
- **Sandbox**
|
||||
- [Website guidelines](../website-guidelines-checklist.md): majority of the
|
||||
- [Website guidelines](../website-guidelines-checklist.md): a majority of the
|
||||
guidelines are satisfied
|
||||
- [Docs assessment][]: consider [submitting a request][service desk] for an assessment
|
||||
as early as possible to avoid documentation and website rework.
|
||||
- **Project documentation** may or may not be present -- it is acceptable at
|
||||
this maturity level to link out to documentation that hasn't yet been
|
||||
integrated into the website
|
||||
- _Example_: website with a single homepage, without any documentation or, as
|
||||
was mentioned above, linking out to an external (preexisting) source for
|
||||
docs
|
||||
- _Example_: website with a single homepage, without any documentation or,
|
||||
as was mentioned above, linking out to an external (preexisting) source
|
||||
for docs
|
||||
- _However_: consider reading the recommended practices in this repository
|
||||
and implementing as many of the best practices as you can. This groundwork
|
||||
will pay big dividends later when you need to upgrade your practices and
|
||||
update your documentation as an incubating project. Assistance is
|
||||
available from CNCF TechDocs anytime, including answers to individual
|
||||
questions or a documentation workshop.
|
||||
- **Incubating**
|
||||
- [Website guidelines][]: all guidelines are satisfied.
|
||||
- [Docs assessment][]: request an (re-)assessment through the CNCF [service
|
||||
|
|
@ -207,7 +214,7 @@ requirements for sandbox projects.
|
|||
- The website repo is in an [archived state][]
|
||||
- The archived status of the project must be obvious to those visiting the
|
||||
website, such as through the use of a prominent banner.
|
||||
- If a successor project exists, link to it's website and/or migration
|
||||
- If a successor project exists, link to its website and/or migration
|
||||
documentation.
|
||||
|
||||
[archived state]:
|
||||
|
|
@ -254,9 +261,9 @@ We evaluate on the following:
|
|||
- Is there an easily recognizable brand for the project (logo + color scheme)
|
||||
clearly identifiable?
|
||||
- Is the brand used across the website consistently?
|
||||
- Is the website’s typography clean and well-suited for reading?
|
||||
- Is the website’s typography clean and legible?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://helm.sh/>
|
||||
|
||||
|
|
@ -282,9 +289,10 @@ Examples:
|
|||
|
||||
### 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,
|
||||
while optional, can offer your readers a site-focused search results.
|
||||
SEO helps users find your project and its documentation, and analytics helps you
|
||||
monitor site traffic and diagnose issues like page 404s. Intra-site search,
|
||||
while optional, offers your readers site-focused search results and is strongly
|
||||
recommended.
|
||||
|
||||
We evaluate on the following:
|
||||
|
||||
|
|
@ -313,7 +321,7 @@ We evaluate on the following:
|
|||
- Are site build times reasonable?
|
||||
- Do site maintainers have adequate permissions?
|
||||
|
||||
Examples:
|
||||
Example:
|
||||
|
||||
- <https://kubernetes.io>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# Assistance program for technical documentation
|
||||
|
||||
This document outlines the Cloud Native Computing Foundation (CNCF) Technical
|
||||
Documentation Assistance Program (the Program), a service offered by CNCF Tech
|
||||
Docs for evaluating and improving an OSS project's technical documentation. The
|
||||
process is designed to:
|
||||
Documentation Assistance Program (the Program), a service offered by CNCF
|
||||
TechDocs for evaluating and improving an OSS project's technical documentation.
|
||||
The process is designed to:
|
||||
|
||||
1. Provide a baseline analysis of the project's documentation quality measured
|
||||
against the project's [maturity level](analysis/criteria.md). Often, projects
|
||||
|
|
@ -18,6 +18,13 @@ process is designed to:
|
|||
1. Leave the project team with an improved understanding and skill base for
|
||||
improving and maintaining the project documentation.
|
||||
|
||||
**Note**: The Program focuses on established projects at the _incubating_ and
|
||||
_graduated_ maturity levels. The Program offers help for _sandbox_ projects as
|
||||
well, but with less emphasis on analyzing existing documentation and more on
|
||||
establishing good practices and starting a minimally viable documentation set.
|
||||
For more information contact the
|
||||
[CNCF TechDocs team](https://servicedesk.cncf.io/).
|
||||
|
||||
## Phase 0: Training
|
||||
|
||||
Some level of familiarity with the technical documentation process is required
|
||||
|
|
|
|||
Loading…
Reference in New Issue