Simplify Contributing

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