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.

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 :)

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.

chalin · 2024-05-31T15:43:42Z

Rebased from main.

nate-double-u · 2024-05-31T15:45:20Z

thansk @chalin, i was just looking to do that (GitHub UI was saying out of date, start over, and it was confusing 😅)

assistance.md

chalin · 2024-05-31T16:08:24Z

@nate-double-u - with all GH actions passing, overall I agree that this looks good. I'd suggest we merge, and then I can make a pass or two to move things around etc. WDYT? As mentioned before the DCO check is failing, but you said that you'd fix it when merging 👍.

chalin

Great improvement!
Next time let's do this via a series of smaller PRs.
LGTM. I'll make a pass or two after.

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: Patrice Chalin <pchalin@gmail.com>

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

… templates. Reorganized tech-docs directory structure. Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.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: Patrice Chalin <pchalin@gmail.com>

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

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

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

Signed-off-by: Patrice Chalin <pchalin@gmail.com>

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

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

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

View reviewed changes

chalin force-pushed the analysis-howto branch from 5f3fd92 to 3bb2c0f Compare May 31, 2024 15:43

nate-double-u reviewed May 31, 2024

View reviewed changes

assistance.md Outdated Show resolved Hide resolved

chalin approved these changes May 31, 2024

View reviewed changes

Omphaloskepsis and others added 10 commits May 31, 2024 12:13

Updated tech doc analysis process.

64bd857

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: Patrice Chalin <pchalin@gmail.com>

Updated.

af91f2f

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

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

f042ad8

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

Apply suggestions from code review

9f2938b

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: Patrice Chalin <pchalin@gmail.com>

Renamed directories, made recommended changes from reviews.

f2b4d9e

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

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

0a855c8

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

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

836c463

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

Reverting CSV file.

438386f

Signed-off-by: David Welsch <dwelsch@expertsupport.com> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

correcting links, reformatting tables, other formatting corrections

5f769ae

Signed-off-by: Nate W <natew@cncf.io> Signed-off-by: Patrice Chalin <pchalin@gmail.com>

Address check failures

edebb31

Signed-off-by: Patrice Chalin <pchalin@gmail.com>

chalin force-pushed the analysis-howto branch from c81ef24 to edebb31 Compare May 31, 2024 16:14

nate-double-u merged commit 81199a2 into cncf:main May 31, 2024
4 checks passed

This was referenced May 31, 2024

Move assessments to analyses and more #245

Merged

Docs and analyses review and updates #247

Open

nate-double-u mentioned this pull request Jun 11, 2024

Update TechDocs Analysis process #212

Closed

nate-double-u mentioned this pull request Aug 21, 2024

Update .cspell.yml ignore list #276

Open

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

Loading

nate-double-u May 16, 2024

chalin left a comment

nate-double-u May 14, 2024

chalin commented May 14, 2024 •

edited

Loading

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

Loading

nate-double-u May 16, 2024

nate-double-u commented May 16, 2024

nate-double-u commented May 16, 2024 •

edited

Loading

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

Loading

nate-double-u commented May 28, 2024

chalin commented May 31, 2024

nate-double-u commented May 31, 2024

chalin commented May 31, 2024

chalin left a comment


		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

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 Loading

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 Loading

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 Loading

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 Loading

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 Loading

nate-double-u commented May 28, 2024

chalin commented May 31, 2024

nate-double-u commented May 31, 2024

chalin commented May 31, 2024

chalin left a comment

Choose a reason for hiding this comment

chalin May 14, 2024 •

edited

Loading

chalin commented May 14, 2024 •

edited

Loading

nate-double-u May 16, 2024 •

edited

Loading

nate-double-u commented May 16, 2024 •

edited

Loading

chalin commented May 28, 2024 •

edited

Loading