From 948eae6cef893babf88e2fd64802eedb2a31a4d9 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 27 Jul 2024 10:21:15 -0700
Subject: [PATCH] Simplify Contributing

---
 docs/source/contributing/index.md | 61 +++++++++++--------------------
 1 file changed, 22 insertions(+), 39 deletions(-)

diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md
index 90d411dffb..0303c19fe6 100644
--- a/docs/source/contributing/index.md
+++ b/docs/source/contributing/index.md
@@ -10,17 +10,12 @@ myst:
 # Contribute to `plone.restapi`
 
 This section describes how to contribute to the `plone.restapi` project.
-It extends {doc}`plone:contributing/index`. 
+It extends {doc}`plone:contributing/index`.
 
 
 ## Pre-requisites
 
-Prepare your system by installing pre-requisites.
-
-
-### System libraries
-
-See {ref}`plone:plone-pre-requisites-label`.
+Prepare your system by installing {ref}`plone:plone-pre-requisites-label`.
 
 
 ## Set up development environment
@@ -32,20 +27,25 @@ To install this package, its dependencies, and its documentation, code formattin
 make
 ```
 
+To see all the Makefile targets and help, use the following command.
+
+```shell
+make help
+```
+
 
 ## Generate documentation examples
 
-This documentation includes examples of requests and responses (http, curl, httpie, and python-requests).
+This documentation includes examples of requests and responses, using each of http, curl, httpie, and python-requests.
 These examples are generated by the documentation tests in `test_documentation.py`.
-To generate a new example, add a new test case to `test_documentation.py`, for example `test_documentation_search_fullobjects`, and run the test
+To generate a new example, add a new test case to `test_documentation.py`, for example `test_documentation_search_fullobjects`, and run the test.
 
 ```shell
 ./bin/test -t test_documentation_search_fullobjects
 ```
 
-This generates the request and the response files in `tests/http-examples/`.
-
-Include them in the documentation using MyST syntax:
+The above command also generates the request and the response files in `tests/http-examples/`.
+Include them in the documentation using MyST syntax.
 
 ````markdown
 ```{eval-rst}
@@ -57,30 +57,14 @@ Include them in the documentation using MyST syntax:
 ```
 ````
 
-Build the documentation locally to test the rendering using the appropriate Makefile target.
+Build the documentation locally to test the rendering.
 
-`docs-clean`
-: Clean current and legacy docs build directories, and Python virtual environment
-
-`docs-html`
-: Build HTML
-
-`docs-linkcheck`
-: Run linkcheck
-
-`docs-linkcheckbroken`
-: Run linkcheck and show only broken links
-
-`docs-livehtml`
-: Rebuild Sphinx documentation on changes, with live-reload in the browser
-
-`docs-vale`
-: Run spell, grammar, and style checks
+```shell
+make docs-html
+```
 
-`docs`
-: Build Docs
+Add and commit the generated files in `src/plone/restapi/tests/http-examples/`.
 
-Make sure you add and commit the generated files in `http-examples`.
 
 ## Conventions
 
@@ -92,17 +76,16 @@ conventions
 
 ## Code formatting and testing
 
-To ensure consistent code formatting, we use [Black](https://black.readthedocs.io/en/stable/index.html).
-All pull requests must pass code formatting checks.
-We recommend that you run Black locally.
-You can use the following command to automatically format the code.
+All changes must pass code formatting and tests.
+Run these checks locally before creating a pull request.
+
+Use the following command to automatically format the code with [Black](https://black.readthedocs.io/en/stable/index.html).
 
 ```shell
 make black
 ```
 
-To run tests locally and ensure your changes don't introduce any issues, use the following command.
-This will execute the test suite and provide test feedback.
+Use the following command to run tests.
 
 ```shell
 make test