📖doc tweaks

README.md

@@ -1,32 +1,53 @@
 # Generation of SLSA3+ provenance for native GitHub projects
 
-This repository contains the implementation for generating non-forgeable [SLSA provenance](https://slsa.dev/) that meets the requirement for the [SLSA level 3 and above](https://slsa.dev/spec/v0.1/levels). The SLSA generation makes use of a [Github Actions reusable workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
+This repository contains tools for generating non-forgeable [SLSA provenance](https://slsa.dev/) on GitHub that meets the [build](https://slsa.dev/spec/v0.1/requirements#build-requirements) and [provenance](https://slsa.dev/spec/v0.1/requirements#provenance-requirements) requirements for [SLSA level 3 and above](https://slsa.dev/spec/v0.1/levels).
 
-This repository contains the code, examples and technical design for the blog post on [Non forgeable SLSA provenance using GitHub workflows](https://security.googleblog.com/2022/04/improving-software-supply-chain.html).
+Use of the provided [Github Actions reusable workflow](https://docs.github.com/en/actions/using-workflows/reusing-workflows)s only is not sufficient to meet all of the requirements at SLSA level 3. Specifically, the [source requirements](https://slsa.dev/spec/v0.1/requirements#source-requirements) are not covered by these workflows and must be handled explicitly to meet all requirements at SLSA level 3+.
+
+This repository contains the code, examples and technical design for system described in the blog post on [Non forgeable SLSA provenance using GitHub workflows](https://security.googleblog.com/2022/04/improving-software-supply-chain.html).
 
 ---
 
-- [Golang projects](#golang-projects)
-- [Other projects](#other-projects)
-- [Provenance format](#provenance-format)
+- [Generation of provenance](#generation-of-provenance)
+  - [Golang projects](#golang-projects)
+  - [Other projects](#other-projects)
+- [Verification of provenance](#verification-of-provenance)
+  - [Installation](#installation)
+  - [Inputs](#inputs)
+  - [Command line examples](#command-line-examples)
 - [Technical design](#technical-design)
   - [Blog post](#blog-post)
   - [Specifications](#specifications)
+  - [Provenance format](#provenance-format)
 
 ---
 
-## Golang projects
+## Generation of provenance
+
+### Golang projects
 
 To generate SLSA provenance for your Golang project, follow [internal/builders/go/README.md](internal/builders/go/README.md).
 
-## Other projects
+### Other projects
 
 To generate SLSA provenance for other programming languages, follow [internal/builders/generic/README.md](internal/builders/generic/README.md).
 This is a pre-release only and we will have the official release in July 2022.
 
-## Provenance format
+## Verification of provenance
 
-The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md).
+To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project.
+
+### Installation
+
+To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation).
+
+### Inputs
+
+The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options).
+
+### Command line examples
+
+A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example).
 
 ## Technical design
 
@@ -38,5 +59,7 @@ Find our blog post series [here](https://security.googleblog.com/2022/04/improvi
 
 For a more in-depth technical dive, read the [SPECIFICATIONS.md](./SPECIFICATIONS.md).
 
+### Provenance format
 
+The format of the provenance is available in [PROVENANCE_FORMAT.md](./PROVENANCE_FORMAT.md).
 

internal/builders/go/README.md

@@ -14,12 +14,6 @@ This document explains how to use the builder for Golang projects.
 - [Example provenance](#example-provenance)
 - [BuildConfig format](#buildconfig-format)
 
-[Verification of provenance](#verification-of-provenance)
-
-- [Installation](#installation)
-- [Inputs](#inputs)
-- [Command line examples](#command-line-examples)
-
 ---
 
 ## Generation
@@ -277,19 +271,3 @@ The `BuildConfig` contains the following fields:
 ```json
   "workingDir": "/home/runner/work/ianlewis/actions-test"
 ```
-
-## Verification of provenance
-
-To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project.
-
-### Installation
-
-To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation).
-
-### Inputs
-
-The inputs of the verifier are described in [slsa-framework/slsa-verifier#available-options](https://github.com/slsa-framework/slsa-verifier#available-options).
-
-### Command line examples
-
-A command line example is provided in [slsa-framework/slsa-verifier#example](https://github.com/slsa-framework/slsa-verifier#example).