[bug] README.md documentation might cause confusion

[olivekl]

I have a few suggestions to improve the documentation in README.md. The goal of these changes is to help users to navigate the information, understand what the builders can offer, and choose between the options.

• Add a short description at top of what this repo contains / what the project does (before going into the explanation of what SLSA is, what provenance is, etc)

You can take from the beginning of “What is slsa-github-generator” if you add some info for people who don’t know about SLSA and provenance
Something like:
“This repository contains free tools to generate and verify SLSA3+ provenance for native GitHub projects using GitHub Actions. Developers can build their software using a secure process that protects against many supply chain attacks and tampering. Users of their software can verify a tamper-proof(resistant?) statement of the process to know how the software was created.”

• Under Generate provenance, add a high-level summary of what factors to consider when choosing a builder. I.e., when someone reads through the descriptions, they’re choosing based on… language? Output? What should they be weighing, and what’s the shortest path to finding the one that’s right for them? Do we have suggestions (i.e., X is best for most common use cases, unless you need foo, in which case, use Y)

• Move Roadmap after the main user journey sections (i.e., after Generate and Verify Provenance, see suggestion below)

• Simplify wording of main user journey headings (Generation of → Generate; Verification of → Verify, see suggestion below)

• This sentence isn’t clear (under “Builders”): “If you would rather build your project yourself, use the generators instead as explained in the next section.” Are you saying: “If you don’t want to use our builders, you can still use the provenance generator to produce provenance for software you build yourself”?

• Similarly, the first sentence under Provenance-only generators is unclear: “Provenance-only generators let you build your artifact, and only generate provenance for you. “ (“Let you build your artifact” can be misunderstood as meaning that the generator is doing the building.)

• Under Verification of Provenance, is it possible to give guidance about how to know whether an artifact’s provenance has been generated by something that can be verified using the tooling provided? It’d be good to add a few sentences for the user who downloads an artifact, gets the provenance, doesn’t know much about this whole SLSA business, and lands on your page and goes immediately to the Verification section. They’d want to know that they’re in the right place, and what verification will do for them to make it worth installing something.

Structure/naming (changes in bold)

• Overview – add a few lines
  • What is SLSA?
  • What is provenance?
  • What is slsa-github-generator?
  • Hall of Fame
    • Provenance Generation
    • Builder Creation
• Generate provenance
  • Referencing SLSA builders and generators
  • Builders
  • Provenance-only generators
• Verify provenance
  • Installation
  • Inputs
  • Command line examples
• Build Your Own Builder
• Project Roadmap
• Technical design
  • Specifications
  • Provenance format
• Contributing