diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2a858a4a..299b11c5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,8 @@
-## Contributing
+# Contributing
 
 Open the project in Xcode and build by Product -> Build.
 
-### Linting code
+## Linting code
 
 Code is automatically linted during a build in Xcode. If you need to manually lint:
 
@@ -11,7 +11,7 @@ brew install swiftlint
 swiftlint
 ```
 
-### Formatting code
+## Formatting code
 
 You can automatically format your code using:
 
@@ -19,7 +19,17 @@ You can automatically format your code using:
 ./scripts/swift-format
 ```
 
-### Running tests
+## API diffs
+We run a script to make sure that we don't make changes to the public API without intending to.
+The diff script and the script to generate a new "golden api file" uses a tool called [SourceKitten](https://github.com/jpsim/SourceKitten) which can be installed using homebrew (`brew install sourcekitten`).
+
+### The expected workflow is:
+* Write code (that may change the public API).
+* Optionally run `./scripts/api_diff.sh` to detect the api change.
+* Run `./scripts/generate_public_api.sh` -- this will update the file in `./api`.
+* Commit both code and the updated API file in the same commit. 
+
+## Running tests
 
 IT tests require a Confidence client token to reach remote servers. The token can be created on the Confidence portal. 
 The Confidence organization used for IT tests is named `confidence-test` (you may need to request access).
diff --git a/scripts/public_api.json b/api/public_api.json
similarity index 100%
rename from scripts/public_api.json
rename to api/public_api.json
diff --git a/scripts/api_diff.sh b/scripts/api_diff.sh
index c70eb144..74f42d74 100755
--- a/scripts/api_diff.sh
+++ b/scripts/api_diff.sh
@@ -17,7 +17,7 @@ rm $script_dir/raw_api.json
 # Compare the public API with the previous public API and exit with 1 if there are changes
 echo "Comparing genereated public API with previous public API"
 set +e
-git diff --no-index --exit-code $script_dir/public_api.json $script_dir/current_public_api.json
+git diff --no-index --exit-code $root_dir/api/public_api.json $script_dir/current_public_api.json
 # Capture the exit code of the git diff command
 diff_exit_code=$?
 set -e
diff --git a/scripts/generate_public_api_list.sh b/scripts/generate_public_api.sh
similarity index 92%
rename from scripts/generate_public_api_list.sh
rename to scripts/generate_public_api.sh
index e0a2c58f..5308952a 100755
--- a/scripts/generate_public_api_list.sh
+++ b/scripts/generate_public_api.sh
@@ -9,7 +9,7 @@ root_dir="$script_dir/../"
 sourcekitten doc --module-name Confidence -- -scheme Confidence-Package -destination 'platform=iOS Simulator,name=iPhone 15,OS=17.2' > $script_dir/raw_api.json
 
 # Extract the public API from the raw api json file
-python3 $script_dir/extract_public_funcs.py $script_dir/raw_api.json $script_dir/public_api.json
+python3 $script_dir/extract_public_funcs.py $script_dir/raw_api.json $root_dir/api/public_api.json
 
 # Clean up the raw api json file
 rm $script_dir/raw_api.json
\ No newline at end of file