22
33## Audience
44
5- This document is for members of the CNCF TechDocs team, including contractors or
6- consultants, who need to conduct or assist with an analysis of a CNCF
7- open-source project's technical documentation.
5+ This document is for members of the CNCF TechDocs team and others who wish to
6+ conduct or assist with an analysis of a CNCF open-source project's technical
7+ documentation.
88
99## Purpose
1010
1111The goals of a CNCF technical documentation analysis are to:
1212
1313- Examine the current project technical documentation and website against the
14- CNCF's analysis framework, as described in the doc analysis
15- [ criteria] ( ./criteria.md ) .
16- - Compare the documentation against the current or proposed maturity level for
17- the overall project.
18- - Recommends a program of key improvements with the largest return on
19- investment. These improvements are documented as _ recommendations_ in the
20- analysis document and expanded in a companion
14+ CNCF's analysis [ criteria] .
15+ - Compare the documentation against the current or proposed [ project
16+ maturity level] .
17+ - Recommend a program of key documentation improvements with the largest return
18+ on investment. These improvements are documented as _ recommendations_ in the
19+ analysis document, and expanded in a companion
2120 [ implementation plan] ( ./templates/implementation.md ) and
22- [ issues backlog ] ( ./templates/umbrella-issue .md ) .
21+ [ issues list ] ( ./templates/issues-list .md ) .
2322
2423## Doing a Tech Docs Analysis
2524
26- The tech docs analysis consists of some repository bookkeeping (Prerequisites ),
25+ The tech docs analysis consists of some repository bookkeeping (prerequisites ),
2726then of three overall tasks:
2827
29- 1 . Write the analysis document: Evaluate the existing project documentation with
30- respect to the project maturity level ( or proposed maturity level, if the
31- analysis is associated with an upgrade request) . Identify gaps with CNCF
32- criteria. Write general recommendations to close the largest and most
33- important gaps .
34- 2 . Write the implementation plan: Decompose the recommendations to specific
28+ 1 . Write the analysis document: evaluate the existing project documentation with
29+ respect to the [ project maturity level] or proposed maturity level, if the
30+ analysis is associated with a project upgrade request. Identify gaps with
31+ CNCF [ criteria] . Write general recommendations to close the largest and most
32+ important identified issues .
33+ 2 . Write a implementation plan: decompose recommendations in to specific
3534 improvement suggestions. These can be additions or revisions to the docs;
3635 reorganization; website infrastructure changes; or any other work that will
37- close the gaps . Make suggestions specific (if you propose reorganizing a
38- section, for example, provide an outline) but provide enough information that
39- a contributor could solve the problem differently if they have a different
40- idea ( make it clear that your proposed outline is only one possible
41- reorganization, e.g.) .
42- 3 . Write the issue backlog.
36+ close address issues . Make suggestions specific enough (for example, if you
37+ propose reorganizing a section then provide an outline) without being overly
38+ constraining so that a contributor could solve the problem differently if
39+ they have a different solution. For example, make it clear that your proposed
40+ outline is only one possible reorganization .
41+ 3 . Write an issue backlog.
4342
44- Finally, there are follow-up steps including creating GitHub issues and a pull
45- request, and getting approval from project maintainers.
43+ Finally, there are follow-up steps including:
44+
45+ - Creating GitHub issues and a pull request
46+ - Getting approval from project maintainers
4647
4748### Prerequisites
4849
49- This process assumes you have some familiarity with GitHub repositories and pull
50- requests (PRs).
50+ This section assumes you are familiar with GitHub repositories and pull requests
51+ (PRs). If you need a refresher, see
52+ [ Get started] ( https://docs.github.com/en/get-started ) from the GitHub docs.
53+
54+ Project analyses are kept in the
55+ [ CNCF tech docs repository] ( https://github.com/cncf/techdocs ) . Clone and prepare
56+ for
5157
52581 . Clone the [ CNCF tech docs repository] ( https://github.com/cncf/techdocs ) .
53- 1 . Create a branch for the analysis.
54- 1 . In the new branch, create a directory for the analysis in the CNCF tech docs
55- /analysis directory. Name the directory ` 00NN-_PROJECT_ ` , where _ NN_ is the
59+ 2 . Create a branch for the analysis.
60+ 3 . In the new branch, create a directory for the analysis in the CNCF tech docs
61+ [ analyses ] directory. Name the directory ` 00NN-_PROJECT_ ` , where _ NN_ is the
5662 next index available in the directory (check for PRs as well, if someone else
5763 is working on tech doc analyses), and where _ PROJECT_ is a short but not
5864 abbreviated project name. For example, for Kubernetes _ PROJECT_ would be
5965 _ kubernetes_ , not _ k8s_ .
60- 1 . Copy and rename the analysis doc templates from the
61- ` /analysis/analysis-tools ` directory as follows: ` analysis-template.md ` >
62- ` _PROJECT_-analysis.md ` ; ` implementation-template.md ` >
63- ` _PROJECT_-implementation.md ` ; and ` umbrella-issue-template.md ` >
64- ` _PROJECT_-issues.md ` .
66+ 4 . Copy all the doc analysis [ templates] .
6567
6668### Writing the Analysis document
6769
68- Edit ` _PROJECT_-analysis.md ` and follow these steps to complete the first step,
69- the analysis:
70+ Follow the steps outlined below as a part of writing the project's analysis
71+ document. Record your findings in the project's
72+ [ analysis.md] ( ./templates/analysis.md ) file.
7073
71- 1 . Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs
72- and repositories included and excluded from the analysis.
73- 1 . Review the in-scope URLs and repositories for compliance with the rubric
74+ 1 . Define the ** scope** of the analysis. Edit "Scope of analysis" to reflect
75+ URLs and repositories included and excluded from the analysis.
76+ 2 . Review the in-scope URLs and repositories for compliance with the rubric
7477 criteria. Note any gaps, as well as any areas that exceed criteria or are
7578 exceptionally well executed. I find it easiest to do this separately for each
7679 of the three areas of concern (project doc, contributor doc, website), making
@@ -81,11 +84,11 @@ the analysis:
8184 level (or proposed maturity level, if the analysis is part of a petition for
8285 upgrade). Write comments to note the most important gaps and best-executed
8386 features of the documentation.
84- 1 . Assign ratings to each criterion based on your comments and compliance with
87+ 3 . Assign ratings to each criterion based on your comments and compliance with
8588 the maturity level expectations in the rubric. The ratings are
8689 self-explanatory. Keep in mind that "needs improvement" or "meets standards"
8790 is with respect to the current (or proposed) maturity level.
88- 1 . Write recommendations. The template implies that you'll do this for every
91+ 4 . Write recommendations. The template implies that you'll do this for every
8992 criterion; the "Recommendations" headings mirror the "Comments" headings.
9093 However, if some alternative framework makes more sense, use that. For
9194 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.
205208
206209### Creating GitHub issues
207210
208- Enter the backlog issues from the issues document into the project documentation
209- GitHub repository using the format in the umbrella-issues-template.md and
210- issues-template.md files. Create one GitHub issue per backlog issue, and create
211- an umbrella issue that contains a checklist item for each issue.
211+ Create issues in the project documentation GitHub repository for:
212+
213+ - Each issues in the [ issues list] .
214+ - An umbrella issue that provides a context for the previously created
215+ individual issues.
216+
217+ [ analyses ] : ../../analyses/
218+ [ criteria ] : ./criteria.md
219+ [ project maturity level ] : https://www.cncf.io/project-metrics
220+ [ templates ] : ./templates/
221+ [ issues list ] : ./templates/issues-list.md
0 commit comments