Going through the Overview page as a first-time reader, I noticed the attacks section explains things really clearly (e.g. "an attacker gives you an older file and tricks you into thinking it's newer"). But the very next section, "How does TUF secure updates?", packs trusted keys, hashes, signatures, metadata versions, and expiration dates all into one paragraph before linking straight to the Roles and metadata page.
Since the attacks are explained so plainly just above it, might be worth breaking this section up the same way — maybe mapping each attack to the specific piece of metadata that stops it, instead of listing everything at once. Could make the jump into Roles and metadata feel less abrupt too.
Happy to draft this as a comment here first before opening anything, just want to check if this is a fix you'd actually want or if I'm missing context on why it's written the way it is.
Going through the Overview page as a first-time reader, I noticed the attacks section explains things really clearly (e.g. "an attacker gives you an older file and tricks you into thinking it's newer"). But the very next section, "How does TUF secure updates?", packs trusted keys, hashes, signatures, metadata versions, and expiration dates all into one paragraph before linking straight to the Roles and metadata page.
Since the attacks are explained so plainly just above it, might be worth breaking this section up the same way — maybe mapping each attack to the specific piece of metadata that stops it, instead of listing everything at once. Could make the jump into Roles and metadata feel less abrupt too.
Happy to draft this as a comment here first before opening anything, just want to check if this is a fix you'd actually want or if I'm missing context on why it's written the way it is.