Docs: TUF docs Analysis and Improvement

Dindihub commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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.

Dindihub commented 5 months ago

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 commented 5 months ago

@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 commented 5 months ago

@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

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

> techdocs@0.0.0 _check:format
> npx prettier --check .

npm warn exec The following package was not found and will be installed: prettier@3.3.2
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 commented 5 months ago

@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

Dindihub commented 4 months ago

Hi @Dindihub - I'm glad that you were able to make progress by using GitPod.io. See inline comment for a means of fixing the markdown check failure. Also please address the formatting failure.

Oh! I'm taken a look right away. Thanks @chalin

Dindihub commented 4 months ago

Hi @chalin I have just pushed with the suggested changes. Kindly run the test again. Thanks

chalin commented 4 months ago

FYI, @nate-double-u - I've added @Dindihub to the techdocs team with Read-only access so that GH actions will run for her PRs with me having to intervene. We can revoke access at the end of the term.

chalin commented 4 months ago

Hi @Dindihub - All checks are passing \o/. I'll have a look as soon as I can tomorrow.

nate-double-u commented 4 months ago

FYI, @nate-double-u - I've added @Dindihub to the techdocs team with Read-only access so that GH actions will run for her PRs with me having to intervene. We can revoke access at the end of the term.

Good idea--I've done that with other mentees on other projects too.

nate-double-u commented 4 months ago

Remember, @chalin, access to this repo is controlled through cncf/people https://github.com/cncf/people/blob/6055a16591376e23ebc1690b5c2162a001fbb8de/config.yaml#L886-L895

Dindihub commented 4 months ago

Hi @chalin . See my edits according to your suggestions. Waiting for input from @lukpueh before working on issues.md. Thanks

Dindihub commented 4 months ago

Great work so far, @Dindihub. Here are a few suggestions.

Thanks for the review @network-charles

network-charles commented 4 months ago

It’s a pleasure.

lukpueh commented 4 months ago

Thanks again for the assessment, @Dindihub! It's really good to get this perspective from someone who's new to the project.

Reading your document and browsing the website I find that there is plenty of good (maybe a bit unstructured) information for the interested person, who just wants to learn about TUF without specific agenda.

The most improvement-worthy part to me is the "Getting started" section. It is currently a mix of quite abstract (Security), quite specific (Metadata and roles, 2x specification) and a bit random (FAQ, Videos) resources.

Renaming "Getting started" to "Documentation", as you suggest, seems like a fine start. But we should also think about contents. Let me float some ideas...

I would say that the "Documentation" section targets

Adopters, and
Contributors

Adopters

Before we dive into specification details, we should make it clear, who can be an adopter and what options they have. IMO adopters can further be divided into repository maintainers and client developers.

Client maintainers depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations (python-tuf, go-tuf, etc...) . Typically, they will pick the language their client is written in.
Repository maintainers can either use an existing TUF repository implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf repository library such as python-tuf, go-tuf, etc.).

For each option we should describe when to use it and where to find relevant usage documentation. Maybe we should also make it clear that end-users cannot just use TUF autonomously. If they want to use TUF, they need to lobby for it with the relevant repository maintainers and client developers.

The Implementations page in the Getting started section already lists some of the information I would like to see here. But it could use better framing, to help adopters decide what tooling to use.

Contributors

Here I think we should make our lives easy and just direct people to the contribution guidelines in the community repo. We can flesh it out there, talk more about subprojects etc.

As with tooling-specific usage documentation above, the project-specific contribution documentation should be the responsibility of the different TUF subprojects. The website and the community repo just forward to those resources.

Independently of these general TUF project contribution docs, we can add "edit this page on GitHub" links to the website, which point to the website source code repo. This is handy for people, who read the website, stumble over e.g. a typo, and feel like fixing it right away.

Dindihub commented 4 months ago

Excellent observations, @Dindihub! This is really helpful, and here's a first round of review (for analysis.md only). I'll follow up with a review of implementation.md shortly.

I left a bunch of comments inline and have one high-level comment:

I couldn't always completely draw the line between the three major areas. Especially, recommendations for contributor documentation are a bit scattered over all areas, even though they are listed as their own area. Is that intended? Maybe it's not so important, as long as the plan for action is clear.

One more thing: It would be really valuable if you could take another close look at the community repo, and make some recommendations about the separation of content. That is, what should be on https://theupdateframework.io/ and what should be in https://github.com/theupdateframework/community.

Thanks for the review @lukpueh . It fills in the gaps I had during the analysis. To respond to your comments:

Number 1: I was following a CNCF guideline for the analysis. It touched on areas of contribution in all the sections. Patrice @chalin can elaborate on why that is.

-Number 2: I'll look at the community section and provide recommendations. I had it out of scope before @chalin suggested to have it in scope. Thanks for the heads-up.

Dindihub commented 4 months ago

Thanks again for the assessment, @Dindihub! It's really good to get this perspective from someone who's new to the project.

Reading your document and browsing the website I find that there is plenty of good (maybe a bit unstructured) information for the interested person, who just wants to learn about TUF without specific agenda.

The most improvement-worthy part to me is the "Getting started" section. It is currently a mix of quite abstract (Security), quite specific (Metadata and roles, 2x specification) and a bit random (FAQ, Videos) resources.

Renaming "Getting started" to "Documentation", as you suggest, seems like a fine start. But we should also think about contents. Let me float some ideas...

I would say that the "Documentation" section targets

Adopters, and

Contributors

Adopters

Before we dive into specification details, we should make it clear, who can be an adopter and what options they have. IMO adopters can further be divided into repository maintainers and client developers.

Client maintainers depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations (python-tuf, go-tuf, etc...) . Typically, they will pick the language their client is written in.

Repository maintainers can either use an existing TUF repository implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf repository library such as python-tuf, go-tuf, etc.).

For each option we should describe when to use it and where to find relevant usage documentation. Maybe we should also make it clear that end-users cannot just use TUF autonomously. If they want to use TUF, they need to lobby for it with the relevant repository maintainers and client developers.

The Implementations page in the Getting started section already lists some of the information I would like to see here. But it could use better framing, to help adopters decide what tooling to use.

Contributors

Here I think we should make our lives easy and just direct people to the contribution guidelines in the community repo. We can flesh it out there, talk more about subprojects etc.

As with tooling-specific usage documentation above, the project-specific contribution documentation should be the responsibility of the different TUF subprojects. The website and the community repo just forward to those resources.

Independently of these general TUF project contribution docs, we can add "edit this page on GitHub" links to the website, which point to the website source code repo. This is handy for people, who read the website, stumble over e.g. a typo, and feel like fixing it right away.

Thanks for the suggestions @lukpueh . These really help in structuring content for the TUF Docsy prototype. I'll be seeking clarification on some issues as we continue. Thanks again

Dindihub commented 4 months ago

Excellent observations, @Dindihub! This is really helpful, and here's a first round of review (for analysis.md only). I'll follow up with a review of implementation.md shortly.

I left a bunch of comments inline and have one high-level comment:

I couldn't always completely draw the line between the three major areas. Especially, recommendations for contributor documentation are a bit scattered over all areas, even though they are listed as their own area. Is that intended? Maybe it's not so important, as long as the plan for action is clear.

One more thing: It would be really valuable if you could take another close look at the community repo, and make some recommendations about the separation of content. That is, what should be on https://theupdateframework.io/ and what should be in https://github.com/theupdateframework/community.

nate-double-u commented 4 months ago

I'm not sure why this got closed, was it by accident?

Dindihub commented 4 months ago

I'm not sure why this got closed, was it by accident?

By accident. Thanks for noticing @nate-double-u . I'll correct it right away.

nate-double-u commented 4 months ago

Reopening

JustinCappos commented 4 months ago

A few other thoughts I discussed with Lukas were: 1) to have some sort of video or similar which is a gentle, ~1 minute overview about why the project matters. @mnm678 might be a good person to record this, if she's interested. 2) The other would be a way for them to schedule an appointment to talk to someone from the community. For repo maintainers this makes a lot of sense because each situation is a bit unique. For end users, that is likely too much for us to handle...

I'm not sure either of these make sense, but will leave it to @chalin, @nate-double-u , and @Dindihub to weigh in.

mnm678 commented 4 months ago

A few other thoughts I discussed with Lukas were:

1. to have some sort of video or similar which is a gentle, ~1 minute overview about why the project matters.  @mnm678 might be a good person to record this, if she's interested.

2. The other would be a way for them to schedule an appointment to talk to someone from the community.  For repo maintainers this makes a lot of sense because each situation is a bit unique.  For end users, that is likely too much for us to handle...

I'm not sure either of these make sense, but will leave it to @chalin, @nate-double-u , and @Dindihub to weigh in.

Happy to help with #1!

chalin commented 4 months ago

A few other thoughts I discussed with Lukas were:

to have some sort of video or similar which is a gentle, ~1 minute overview about why the project matters. @mnm678 might be a good person to record this, if she's interested.

The other would be a way for them to schedule an appointment to talk to someone from the community. For repo maintainers this makes a lot of sense because each situation is a bit unique. For end users, that is likely too much for us to handle...

I'm not sure either of these make sense, but will leave it to @chalin, @nate-double-u , and @Dindihub to weigh in.

@Dindihub - add these as suggested improvements. The video could be added to the homepage, and the we could add a "Schedule an appointment" icon to the footer (under the user section), which will then also appear under the community page.

chalin commented 4 months ago

By the way @Dindihub, you might need to expand the following to see all of the comments that were added earlier. Sometimes GitHub folds comments and "hides" them when there are many:

chalin commented 4 months ago

Finally, once you are done editing @Dindihub, ensure that you address the check failures:

lukpueh commented 4 months ago

I propose that we mark this analysis as Status: Draft (or Work-in-progress) so that we can get it merged -- I've added a suggested edit that introduces such a "Status" marker to the main README file. We can then continue to iteratively improve on it. WDYT @lukpueh @JustinCappos.

Works for me. But I think Sandra should at least fix the flagged typos (that is click on apply suggestion) and somewhere note down the comments that will be addressed in a subsequent PR.

Dindihub commented 4 months ago

Thanks for addressing most of my comments, @Dindihub! Can you give it another pass and see if any comments remain unaddressed as @chalin pointed? Please also look at the reviews from @chalin and @network-charles.

You don't have to fix everything here, but at least acknowledge the comments and make sure that they are not lost when we merge this PR. You could e.g. issues (or a summary issues).

@lukpueh I sure will. Thanks for pointing out some of the comments. I realized I had skipped some.

Dindihub commented 4 months ago

A few other thoughts I discussed with Lukas were:

to have some sort of video or similar which is a gentle, ~1 minute overview about why the project matters. @mnm678 might be a good person to record this, if she's interested.

The other would be a way for them to schedule an appointment to talk to someone from the community. For repo maintainers this makes a lot of sense because each situation is a bit unique. For end users, that is likely too much for us to handle...

I'm not sure either of these make sense, but will leave it to @chalin, @nate-double-u , and @Dindihub to weigh in.

@Dindihub - add these as suggested improvements. The video could be added to the homepage, and the we could add a "Schedule an appointment" icon to the footer (under the user section), which will then also appear under the community page.

This is done. Thanks

cncf / techdocs

Docs: TUF docs Analysis and Improvement #261