Revised TechDoc Analysis Tools #229

dwelsch-esi · 2024-05-03T23:07:48Z

Updated READMEs, how-to, and templates for CNCF tech docs analyses. Changes reflect the changes and additions to the tech docs analysis project since November 2023. Reorganized the tech docs directories.

dwelsch-esi · 2024-05-03T23:16:40Z

@chalin @thisisobate @krook @nate-double-u I've updated the tech-docs analysis process documentation, including the howto, templates, and READMEs. I've also re-arranged the directory structure to reflect naming changes we agreed on (for example "analysis" instead of "assessment", and to better contain the analysis materials. Please review. This is a first draft and I'm sure there will be changes -- I need your feedback!

analysis/0001-contour.md

chalin · 2024-05-14T15:37:32Z

README.md

 ## Office hours

-The CNCF tech docs team generally 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](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours).


We had agreed to call these meetings something other than Office Hours. Just a note in passing. We can update in a followup PR.

README.md

chalin · 2024-05-14T16:19:21Z

TechDoc-Assistance-Program.md

Rename to techdocs-assistance.md, or maybe just assistance.md given that this entire repo is about techdocs :)

I agree, and think I prefer just assistance.md here.

TechDoc-Assistance-Program.md

analysis/0001-contour.md

chalin

Thanks @dwelsch-esi. See inline comments.

Also, I suggest:

Reverting the rename of the docs folder to resources
Renamed the analysis folder to analyses
Move & rename /analysis/analysis-tools to /resources so that analyses contains only analyses.
Atm, there should be only templates in the (new) /resources: move the other pages to be under docs:

TechDoc-Assistance-Program.md

nate-double-u · 2024-05-14T17:18:46Z

analysis/analysis-tools/criteria.md

Let's add a README.md file to the analysis-tools directory to build an index in.

chalin · 2024-05-14T19:27:48Z

@dwelsch-esi - after addressing the suggested changes, pls rebase, resolve conflicts, and push back the PR (otherwise rebasing might cause the suggestions to be lost).

chalin

More copyedits

TechDoc-Assistance-Program.md

chalin · 2024-05-14T19:36:57Z

TechDoc-Assistance-Program.md

+
+A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer:
+
+1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are:


A bit of a run-on sentence, consider revising.

TechDoc-Assistance-Program.md

chalin · 2024-05-14T19:43:19Z

TechDoc-Assistance-Program.md

+
+Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process.
+
+We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance. 


@nate-double-u - Do we want to mention mentorship opportunities twice(?) a year?

TechDoc-Assistance-Program.md

chalin · 2024-05-14T19:55:10Z

TechDoc-Assistance-Program.md

+
+Measurement is vital to any process improvement effort, and this is currently the weakest point of the TechDoc Assistance Program. We do no offer any tools to measure the impact of doc improvements, although we can assure you that they are profound. Projects are encouraged to collect metrics on documentation effectiveness. 
+
+As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project.


Hmm, I'm not sure about this paragraph. How about (or just drop the paragraph IMHO):

Suggested change

As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project.

Projects can also track the issue backlog as a means of measuring the increased documentation maturity.

TechDoc-Assistance-Program.md

dwelsch-esi

Reconciling last few commits plus in-toto assessment commit.

nate-double-u · 2024-05-16T21:50:59Z

docs/criteria.md

I think that the docs/criteria.md and docs/howto.md files should be housed in the new resources folder.

I take it back. I think we should create an analysis folder in docs, which would contain the howto and criteria files, and the resources folder, to parallel how we've organized the localization folder.

this leaves the top level analysis folder as a listing of completed assessments.

Added new analysis templates. Renamed directories to better reflect their contents. Rewrote README files. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

… templates. Reorganized tech-docs directory structure. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com>

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

…y structure chnages included. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

nate-double-u · 2024-05-16T22:23:44Z

I'll fix the DCO issue on squash.

nate-double-u · 2024-05-16T22:25:42Z

Let's review and agree on this folder stucture, and if we agree merge, then in a follow up PR do the assessment to analysis folder rename.

dwelsch-esi · 2024-05-16T22:45:38Z

The howto.md file is now in docs/analysis, so you can't automatically view the diff in the PR files view. I've pasted them here so you can just chuck them into your favorite diff tool if you like, though they're different enough that I suspect you'll just want to review the new file standalone. analysis-howto.md is the new file.

analysis-howto.md
main-howto.md

nate-double-u · 2024-05-28T00:55:52Z

README.md

+
+The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].
+
+[assistance-program]: ./techdoc-assistance.md


Where should this link now?

nvm, found it :)

Signed-off-by: Nate W <natew@cncf.io>

nate-double-u · 2024-05-28T01:17:10Z

I've gone through and corrected most links (except those in the templates section, @chalin, we may need to add an exclusion for the check), and have reformatted some tables and other things.

nate-double-u

/lgtm

but I'll let @chalin do a last once over before merging.

chalin · 2024-05-28T22:03:15Z

Thanks all! Was OOO last week, and was catching up until now. I'll review this ~~tomorrow morning~~ as soon as I can.

@nate-double-u - who needs to fix the DCO-check failure?

nate-double-u · 2024-05-28T22:11:32Z

I'll fix that on squash/merge.

dwelsch-esi force-pushed the analysis-howto branch from c825ff8 to 7e00318 Compare May 3, 2024 23:10

nate-double-u reviewed May 13, 2024

View reviewed changes

analysis/0001-contour.md Outdated Show resolved Hide resolved

This was referenced May 14, 2024

24Q1-Q4 planning and activity log for Patrice #227

Open

Basic tooling: link & spell check, and formatting #231

Merged

chalin reviewed May 14, 2024

View reviewed changes

TechDoc-Assistance-Program.md Outdated Show resolved Hide resolved

nate-double-u reviewed May 14, 2024

View reviewed changes

chalin reviewed May 14, 2024

View reviewed changes

dwelsch-esi commented May 15, 2024

View reviewed changes

TechDoc-Assistance-Program.md Outdated Show resolved Hide resolved

dwelsch-esi commented May 16, 2024

View reviewed changes

nate-double-u reviewed May 16, 2024

View reviewed changes

Omphaloskepsis and others added 8 commits May 16, 2024 15:21

Updated tech doc analysis process.

04a7d9f

Added new analysis templates. Renamed directories to better reflect their contents. Rewrote README files. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Updated.

0c0ebe0

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Completed first draft of tech doc analysis READMEs, instructions, and…

9ea8f48

… templates. Reorganized tech-docs directory structure. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Apply suggestions from code review

862591c

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com>

Renamed directories, made recommended changes from reviews.

794c924

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Temporarily renamed analyses back to assessments to merge in-toto change

d594b05

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Final (hopefully) changes to the techdoc analysis materials. Director…

5cefbf9

…y structure chnages included. Signed-off-by: David Welsch <dwelsch@expertsupport.com>

Reverting CSV file.

cd7192f

Signed-off-by: David Welsch <dwelsch@expertsupport.com>

nate-double-u force-pushed the analysis-howto branch from f2beac6 to cd7192f Compare May 16, 2024 22:22

nate-double-u requested review from chalin and nate-double-u May 16, 2024 22:26

nate-double-u mentioned this pull request May 28, 2024

Nw 2024 05 27 analysis howto update #241

Closed

nate-double-u reviewed May 28, 2024

View reviewed changes

correcting links, reformatting tables, other formatting corrections

5f3fd92

Signed-off-by: Nate W <natew@cncf.io>

nate-double-u approved these changes May 28, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Revised TechDoc Analysis Tools #229

Revised TechDoc Analysis Tools #229

dwelsch-esi commented May 3, 2024

dwelsch-esi commented May 3, 2024

chalin May 14, 2024

chalin May 14, 2024 •

edited

nate-double-u May 16, 2024

chalin left a comment

nate-double-u May 14, 2024

chalin commented May 14, 2024 •

edited

chalin left a comment

chalin May 14, 2024

chalin May 14, 2024

chalin May 14, 2024

dwelsch-esi May 15, 2024

dwelsch-esi left a comment

nate-double-u May 16, 2024

nate-double-u May 16, 2024 •

edited

nate-double-u May 16, 2024

nate-double-u commented May 16, 2024

nate-double-u commented May 16, 2024 •

edited

dwelsch-esi commented May 16, 2024

nate-double-u May 28, 2024

nate-double-u May 28, 2024

nate-double-u commented May 28, 2024

nate-double-u left a comment

chalin commented May 28, 2024 •

edited

nate-double-u commented May 28, 2024


		A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed by the CNCF Tech Docs program, the writer:

		1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project, based on a number of criteria in three categories, using a rubric developed by CNCF. The categories are:


		Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process.

		We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance.


		Measurement is vital to any process improvement effort, and this is currently the weakest point of the TechDoc Assistance Program. We do no offer any tools to measure the impact of doc improvements, although we can assure you that they are profound. Projects are encouraged to collect metrics on documentation effectiveness.

		As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project.

	As a basic gauge the effectiveness of the documentation effort, projects can track the issue backlog. This can provide a guide to progress on leveling the documentation maturity to that of the project.
	Projects can also track the issue backlog as a means of measuring the increased documentation maturity.


		The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance-program][].

		[assistance-program]: ./techdoc-assistance.md

Revised TechDoc Analysis Tools #229

Are you sure you want to change the base?

Revised TechDoc Analysis Tools #229

Conversation

dwelsch-esi commented May 3, 2024

dwelsch-esi commented May 3, 2024

Choose a reason for hiding this comment

chalin May 14, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin commented May 14, 2024 • edited

chalin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dwelsch-esi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nate-double-u May 16, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nate-double-u commented May 16, 2024

nate-double-u commented May 16, 2024 • edited

dwelsch-esi commented May 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nate-double-u commented May 28, 2024

nate-double-u left a comment

Choose a reason for hiding this comment

chalin commented May 28, 2024 • edited

nate-double-u commented May 28, 2024

chalin May 14, 2024 •

edited

chalin commented May 14, 2024 •

edited

nate-double-u May 16, 2024 •

edited

nate-double-u commented May 16, 2024 •

edited

chalin commented May 28, 2024 •

edited