From 5f3fd922a89738f3b8acd1eb4c839299117ed9a8 Mon Sep 17 00:00:00 2001 From: Nate W Date: Mon, 27 May 2024 18:15:56 -0700 Subject: [PATCH] correcting links, reformatting tables, other formatting corrections Signed-off-by: Nate W --- README.md | 14 ++-- assessments/README.md | 4 +- docs/analysis/criteria.md | 6 +- docs/analysis/howto.md | 4 +- docs/analysis/resources/README.md | 4 +- docs/analysis/resources/analysis-template.md | 78 ++++++++++---------- 6 files changed, 55 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index cb9738c..6a2748b 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,11 @@ This repository holds resources provided by the CNCF Technical Documentation tea 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 +| 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. @@ -21,7 +21,7 @@ Various consultants and volunteers also contribute to CNCF Tech Docs projects. 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). -Office hours started on 30 September, 2020. +Office hours started on 30 September 2020. ### Meeting link @@ -35,7 +35,7 @@ We store ongoing meeting notes in a [Google doc](https://docs.google.com/documen The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][]. -[assistance-program]: ./techdoc-assistance.md +[assistance-program]: ./assistance.md ### Resources diff --git a/assessments/README.md b/assessments/README.md index 99d212e..84034f2 100644 --- a/assessments/README.md +++ b/assessments/README.md @@ -4,9 +4,9 @@ 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). +- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](../docs/analysis/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 [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). +- 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 [implementation plan](../docs/analysis/resources/implementation-template.md) and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md). ## Audience diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 138ad68..258783b 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -161,7 +161,7 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../docs/website-guidelines-checklist.md): majority of the guidelines are satisfied + - [Website guidelines](../../docs/website-guidelines-checklist.md): 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 @@ -190,11 +190,11 @@ requirements for sandbox projects. documentation. [archived state]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories -[docs assessment]: /assessments/howto.md +[docs assessment]: ./howto.md [maturity level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [service desk]: https://servicedesk.cncf.io [single-source requirement]: #single-source-requirement -[website guidelines]: /howto/website-guidelines-checklist.md +[website guidelines]: ../website-guidelines-checklist.md ### Usability, accessibility and devices diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index f4c56d9..fd34556 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -11,14 +11,14 @@ 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 [implementation plan](./implementation-template.md) and [issues backlog](./umbrella-issue-template.md). +- 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 [implementation plan](./resources/implementation-template.md) and [issues backlog](./resources/umbrella-issue-template.md). ## Doing a Tech Docs Analysis 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 reqeust). Identify gaps with CNCF criteria. Write general recommendations to close the largest and most important gaps. +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 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. diff --git a/docs/analysis/resources/README.md b/docs/analysis/resources/README.md index cd9f414..6d1e728 100644 --- a/docs/analysis/resources/README.md +++ b/docs/analysis/resources/README.md @@ -11,5 +11,5 @@ Use the templates in this directory to perform a documentation analysis for CNCF Resources for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][], are in the `docs` directory. -[how-to]: ../docs/howto.md -[criteria]: ../docs/criteria.md \ No newline at end of file +[how-to]: ../howto.md +[criteria]: ../criteria.md \ No newline at end of file diff --git a/docs/analysis/resources/analysis-template.md b/docs/analysis/resources/analysis-template.md index 6d2cbd3..f4eb661 100644 --- a/docs/analysis/resources/analysis-template.md +++ b/docs/analysis/resources/analysis-template.md @@ -91,13 +91,13 @@ _PROJECT_ is a **graduated** project of CNCF. This means that the project should _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| 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) | +| 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) | _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| 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) | +| 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) | _PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| 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) | +| 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) |