Docs: TUF docs Analysis and Improvement

[Dindihub]

This PR covers issue #162 CNCFSD-1516 Do a first look at the TUF project docs

This is an ongoing exercise so I will be adding content periodically. To see what I'm working on go to analyses/0012-TUF

Maintainers can review routinely and suggest changes.

[nate-double-u]

Thanks for this, @Dindihub; congrats on your selection to the mentorship program!

I'll let your mentors review this, but we do need each commit to be signed. You can see details on how to do that here: https://github.com/cncf/techdocs/pull/261/checks?check_run_id=26370655815. This, like the formatting workflows, doesn't have to happen right away, but we'll need the commits signed before the PR is approved (and it's easier to manage if you get to it earlier in the process).

/cc @chalin @JustinCappos @lukpueh

[Dindihub]

Thanks for this, @Dindihub; congrats on your selection to the mentorship program!

I'll let your mentors review this, but we do need each commit to be signed. You can see details on how to do that here: https://github.com/cncf/techdocs/pull/261/checks?check_run_id=26370655815. This, like the formatting workflows, doesn't have to happen right away, but we'll need the commits signed before the PR is approved (and it's easier to manage if you get to it earlier in the process).

/cc @chalin @JustinCappos @lukpueh

Noted. Thanks Nate

[lukpueh]

Thanks for the great recommendations, @Dindihub! Do you plan to work on any of those? :)

Also, what's the plan for this PR? You say, you want to add content periodically. So it should stay open? I can give it a thorough pass (for typos, etc.) when you think it's ready.

[Dindihub]

Thanks for the great recommendations, @Dindihub! Do you plan to work on any of those? :)

Also, what's the plan for this PR? You say, you want to add content periodically. So it should stay open? I can give it a thorough pass (for typos, etc.) when you think it's ready.

Thanks for asking @lukpueh . I thought to create this PR so you can see what I'm working on. I'll create an implementation soon once @chalin reviews my work.

I'll be sure to notify you and Justin to review once it's ready. I intend for this PR to stay open untill then , so you can review it as a whole. Thanks

[chalin]

Hi @Dindihub, thanks for the PR, and your patience in getting some feedback. Before we start a formal review, let's get all checks passing (fixing broken links etc), including the DCO requirements, as Nate pointed out. Let me know if you have any questions about how to do that.

[chalin]

@Dindihub - let's change the naming convention for the pages in this project. Specifically, rename the TUF-abc.md files by dropping the TUF- prefix.

(Using a prefix made sense when the analysis was in a single file, but not here.)

The rename might also fix some of the broken links.

[Dindihub]

Hi @Dindihub, thanks for the PR, and your patience in getting some feedback. Before we start a formal review, let's get all checks passing (fixing broken links etc), including the DCO requirements, as Nate pointed out. Let me know if you have any questions about how to do that.

Thanks for the review @chalin. Let me work on it again. I have some questions about DCO for you on Slack. Thanks

[Dindihub]

@Dindihub - let's change the naming convention for the pages in this project. Specifically, rename the TUF-abc.md files by dropping the TUF- prefix.

(Using a prefix made sense when the analysis was in a single file, but not here.)

The rename might also fix some of the broken links.

Noted. Thanks @chalin

[chalin]

@Dindihub - for each of the failed PR checks, click on Details at the extreme right to see the run log for any specific failed check.

For example, if you visit https://github.com/cncf/techdocs/actions/runs/9693237225/job/26773151326?pr=261, you'll see:

Run npm run check:format

> [email protected] check:format
> npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)


> [email protected] _check:format
> npx prettier --check .

npm warn exec The following package was not found and will be installed: [email protected]
Checking formatting...
[warn] analyses/00[12](https://github.com/cncf/techdocs/actions/runs/9693237225/job/26773151326?pr=261#step:4:13)-TUF/analysis.md
[warn] analyses/0012-TUF/implementation.md
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.
[help] Run: npm run fix:format
Error: Process completed with exit code 1.

Notice the [help] line tells you which command to run on your local machine to fix the formatting issues.

Fix the formatting first (using npm run fix:format) and that will address many (if not all) of the markdown check failures.

[Dindihub]

@Dindihub - for each of the failed PR checks, click on Details at the extreme right to see the run log for any specific failed check.

For example, ...
Notice the [help] line tells you which command to run on your local machine to fix the formatting issues.

Fix the formatting first (using npm run fix:format) and that will address many (if not all) of the markdown check failures.

Ah. Noted. Thanks

[chalin]

LGTM ✨

Let's merge; we can always make adjustments as we discover necessary edits.