search

cncf / techdocs

CNCF TechDocs Team
https://www.cncf.io
Apache License 2.0
37 stars 26 forks source link

Revised TechDoc Analysis Tools #229

Closed dwelsch-esi closed 1 month ago

dwelsch-esi commented 1 month ago

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 commented 1 month ago

@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!

chalin commented 1 month ago

@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).

nate-double-u commented 1 month ago

I'll fix the DCO issue on squash.

nate-double-u commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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.

chalin commented 1 month ago

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 commented 1 month ago

I'll fix that on squash/merge.

chalin commented 1 month ago

Rebased from main.

nate-double-u commented 1 month ago

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

chalin commented 1 month ago

@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 👍.