Add more about automation

docs/automation-proposals.md

@@ -23,11 +23,12 @@ badge entry data:
   doesn't let the user use the UI to review the changes.
   That said, see [api](./api) if you want more information.
 * Our automation systems examine the project repo for information.
-  This includes looking for a [`.bestpractices.json`](bestpractices-json)
+  This includes looking for a [`.bestpractices.json`](./bestpractices-json.md)
   file which stores
   proposed answers; you can even get the JSON results from another repository
   and use that as a starting point. We also examine the
-  `security-insights.yml` file to determine proposed answers.
+  [`security-insights.yml`](https://security-insights.openssf.org/) file,
+  if present, to determine proposed answers.
   However, these approaches require that you put information into the
   project repository.
 

docs/bestpractices-json.md

@@ -1,16 +1,38 @@
 # bestpractices.json
 
-If a project repository has a `.bestproactices.json` file in its top-level
-(or in a `.projects.d` subdirectory), that information is used as
+If a project repository has a `.bestpractices.json` file in its top-level
+(or in a `.projects.d` subdirectory), that information is used to fill in
 proposed answers.
 
-Important: `?` or `"unknown"` means **"I don't know the answer"**
+## Building on other projects
+
+It's common for one repo in an organization to be similar to another.
+You can use this mechanism to simplify copying information from one
+repo to another.
+
+A useful approach is to work to earn a badge for one project
+in an organization.
+You can then download its status as
+`https://bestpractices.dev/projects/NUMBER.json`.
+Edit the result to record just what's true, and put it in your other project.
+
+In a `.bestpractices.json` file,
+a status `?` or `"unknown"` means **"I don't know the answer"**
 and are **ignored entirely**.
 This lets you safely reuse JSON files containing placeholder `?` values
+That means that if you forget to remove a `?` placeholder, no problem,
+it will be ignored.
+
+## Triggering automation
+
+Whenever you *first* edit a project for a given section, we run automations
+to try to fill in information.
 
-This design allows projects to copy `.bestpractices.json` files from templates
-or other projects that are filled with `?` placeholders without accidentally
-clearing their existing answers.
+After that, if you want to trigger full automation, click on
+"Save (and continue) 🤖". The robot icon 🤖 is a hint that this is the
+way to re-trigger full automation analysis. You'll need to do that
+if you've already saved some answers and have changed the
+`.bestpractices.json` file.
 
 ## Related Documentation