Have more understandable ELI5 about TUF...

[JustinCappos]

TUF is too hard for many folks to get the core concepts. We need something that 'explains like I am five years old' (ELI5 for TUf) that provides a very basic explanation that shows why the project matters, how to use it, etc.

This could be via a video, webpage updates, childrens' books, or any combination.

I feel like I don't have the best ability to judge how to do this, so I'm hopeful we can get the community to weigh in and help out.

[vipulpandey21]

You mentioned you weren't sure how to judge this, so here is a data point rather
than an opinion.

I scored the current pages with the standard readability formulas, counting
prose only, with front matter, code blocks, shortcodes, tables and URLs stripped
out first. Weighted by page length the site averages a Flesch-Kincaid grade of
11 and a reading ease of 42. A reading ease in the 40s is usually described as
difficult, and writing aimed at a general audience normally targets grade 9 or
below.

The interesting part is that it is not spread evenly:

• docs/overview.md and docs/getting-started.md both come out around grade
  9.8, so the introductory path is in reasonable shape already.
• docs/faq.md is grade 11.2, has 21% of its sentences running over 25 words,
  and is the second densest page on the site for specialist vocabulary. Readers
  often arrive at an FAQ directly from a search engine rather than by working
  through the docs in order.
• docs/metadata.md carries the heaviest vocabulary load, 9.2 specialist terms
  per 100 words. That is arguably fair for the subject, but it is the third page
  in the docs nav, right after Overview and Getting started.

If that holds up, the difficulty may be less about the introductory pages
themselves and more about the step up to Roles and metadata. Someone can get
through Overview and Getting started feeling fine, then lose the thread on the
next page.

I have opened #144 and #145 with the tooling behind these numbers, so they can
be re-run and checked rather than taken on trust. It does not write any ELI5
content, it just gives this issue a baseline and a way to tell whether a rewrite
actually helped.

Happy to be told the metrics are measuring the wrong thing. They only capture
sentence length and word complexity, so they cannot tell whether an explanation
is any good, only how dense it looks. Testing with real readers is still the
part that matters.

[rghvbgdi]

hey @JustinCappos @kairoaraujo myself raghav , i am an ex SWE intern at VISA and i have even worked as video edtior :) in my final year of university, for that very reason i stumbled on this particular project on the LFX page . I have done something very similar when working for VISA to document and create demo videos for their latest agentic applications along with coding stuff.

I would love to give a shot here too. Is there any specific portion you guys would want me to cover in a maybe 60 second video , otherwise i will go along with showcasing what goes wrong without TUF , like i saw in the slack channel about notepad++ update hijack, could create something around that showing how usefull TUF actually is.

[yashwaghmare123]

hey @JustinCappos @kairoaraujo ,I tried working on an ELI5 version for this issue. I kept the original content and made it easier to understand for someone new to TUF.I would love to get your feedback on the approach before I go ahead.

[charantejguniganti]

Hi @JustinCappos @kairoaraujo I realized that my previous comment was intended for Issue #110 rather than #132. Please disregard that proposal here; I don't want to introduce unrelated scope into this discussion. For #132, I'll wait for maintainer direction on the ELI5 approach and any areas where I can contribute.

[charantejguniganti]

Hi @jku! I'd like to work on this issue as a follow-up contribution to TUF. I inspected the current issue and the TUF specification, and this looks like a good opportunity to improve interoperability coverage for the recommended keytype/scheme combinations.

My initial approach would be to keep the existing/default key configuration for the general tests and add focused coverage for the three combinations called out in the issue: rsa/rsassa-pss-sha256, ecdsa/ecdsa-sha2-nistp256, and ed25519/ed25519, following the existing test patterns in the repository.

Would you be happy with this approach?

[jitendravjh]

Drafted a plain language page for the four roles, since that seems to be where new readers get stuck: https://gist.github.com/jitendravjh/09d7bd79c3b946692364097a374479a1

First time contributor so leaving it as a comment per #159 rather than a PR. Happy to open one if useful.

[lambaaryan011]

Hi @JustinCappos and @kairoaraujo ,

I'm planning to apply for this through LFX Mentorship, but wanted to introduce myself here first.

I've contributed to Open Climate Fix before (a GSoC org) — mostly codebase refactoring and workflow cleanup. One PR refactored around 24,000 lines: openclimatefix/merge-all-contributors#12. I also worked on a couple of workflow/docs PRs: openclimatefix/pvnet#350 and openclimatefix/.github#76.

Agree with what @vipulpandey21 shared about the Flesch-Kincaid scores. I looked through the metadata.md page today to get a feel for how I'd approach the ELI5 side of this. My basic idea: keep the technical details (metadata, hashes, delegation) accurate, but explain them through something people already understand.

Here's a rough example for the Targets Metadata section:

Think of it like a school field trip. The target files are the actual updates people need — they're like the students getting on the bus. targets.json is the teacher's list: it says how many kids there are and what they look like (their hashes and sizes), so no fake one sneaks on. If it's a big trip, the teacher can't check every student alone, so they hand off smaller lists to a few parent chaperones, each one responsible for their own small group instead of the teacher checking everyone.

Still putting together my full portfolio for the actual application, but wanted to share this first and get your thoughts before I apply properly.

[tannaya7]

Spent a couple days reading through this before deciding what to actually propose.

Went and checked the docs nav weights myself after seeing @vipulpandey21 's readability numbers above overview is 100, getting-started is 200, and metadata.md is 300. So it's literally the third page a new reader hits, and it opens straight into "signature threshold" and "Canonical JSON" with zero build-up. The data lines up with what's actually there.

My instinct is that starting from an attack works better than starting from architecture e.g. "attacker gets the Targets key but not Root," then work backward into why the roles are split up like that. Gives the "why" before the terminology instead of hoping it clicks later.

Also not sure "five-year-old" should be literal, probably closer to a competent developer who's just never touched supply-chain security before.

One thing missing so far: nobody's said how we'd check if any of this actually works. The outcomes explicitly ask for it to be validated, not just written. I'd want to test a draft on a couple of non-security people before/after and see if they can answer "what does TUF actually stop."

Would want this as a real page in the docs, not a separate site- happy to build and ship it myself, including any small interactive bits if that ends up being the right call.