correcting links, reformatting tables, other formatting corrections

Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Patrice Chalin <pchalin@gmail.com>
cncf · May 31, 2024 · 5f769ae · 5f769ae
1 parent 438386f
commit 5f769ae
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 55 deletions.
diff --git 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                    |
 
 <!-- cSpell:ignore chalin nate thisisobate -->
 
@@ -23,7 +23,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
 
@@ -37,7 +37,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
@@ -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
@@ -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
@@ -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
@@ -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
+[how-to]: ../howto.md
+[criteria]: ../criteria.md
diff --git 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
 <!-- 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.
 
-| 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) |
 
 <!-- Rating values:
 1 - not present
@@ -198,12 +198,12 @@ _PROJECT_ is a **graduated** project of CNCF. This means that the project should
 <!-- 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.
 
-| 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) | 
 
 <!-- Rating values:
 1 - not present
@@ -282,22 +282,22 @@ _PROJECT_ is a **graduated** project of CNCF. This means that the project should
 <!-- 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.
 
-| 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) |
 
 <!-- Rating values:
 1 - not present
@@ -339,16 +339,16 @@ documented strategy for managing mirrored files and new contributions.
 
 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][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 |
 
 [git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
-[website-guidelines]: /../../resources/website-guidelines-checklist.md
+[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
 
@@ -462,7 +462,7 @@ We evaluate on the following:
 
 [project-website]: _PROJECT-WEBSITE_
 [project-doc-website]: _PROJECT-DOC-URL_
-[criteria-doc]: ./criteria.md
+[criteria-doc]: ../criteria.md
 [implementation-template]: ./implementation-template.md
 [issues-template]: ./issue-template.md
 [umbrella-template]: ./umbrella-issue-template.md
@@ -472,5 +472,5 @@ We evaluate on the following:
 [contributor-heading]: #contributor-documentation
 [website-heading]: #website
 [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119
-[website-guidelines]: ../../resources/website-guidelines-checklist.md
+[website-guidelines]: ../../website-guidelines-checklist.md