From bec60afba146c24d3d2a59d297edab15e4c8cef5 Mon Sep 17 00:00:00 2001
From: Timid Robot Zehta <timid@creativecommons.org>
Date: Thu, 26 Oct 2023 13:23:26 -0700
Subject: [PATCH 1/2] reorganize development documentation

---
 README.md | 85 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 48 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index 5999abc1..c6addb6e 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ This project seeks to quantify the size and diversity of the commons--the
 collection of works that are openly licensed or in the public domain.
 
 
-## Code of Conduct
+## Code of conduct
 
 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md):
 > The Creative Commons team is committed to fostering a welcoming community.
@@ -27,7 +27,6 @@ collection of works that are openly licensed or in the public domain.
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 
-
 ## Development
 
 
@@ -35,61 +34,72 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 This repository uses [pipenv][pipenvdocs] to manage the required Python
 modules:
-- Linux: [Installing Pipenv][pipenvinstall]
-- macOS:
-  1. Install [Homebrew][homebrew]
-  2. Install pipenv:
+1. Install `pipenv`:
+   - Linux: [Installing Pipenv][pipenvinstall]
+   - macOS:
+     1. Install [Homebrew][homebrew]
+     2. Install pipenv:
         ```shell
         brew install pipenv
         ```
-  3. Create the Python virtual environment and install prerequisites using
-     `pipenv`:
-        ```shell
-        pipenv sync --dev
-        ```
-  4. Then you can run the static analysis tools:
-        ```shell
-        ./tools.sh
-        ```
+  - Windows: [Installing Pipenv][pipenvinstall]
+2. Create the Python virtual environment and install prerequisites using
+   `pipenv`:
+    ```shell
+    pipenv sync --dev
+    ```
 
 [pipenvdocs]: https://pipenv.pypa.io/en/latest/
+[pipenvinstall]: https://pipenv.pypa.io/en/latest/installation/
 [homebrew]: https://brew.sh/
-[pipenvinstall]: https://pipenv.pypa.io/en/latest/install/#installing-pipenv
 
 
-### Running Scripts that Require Client Credentials
+### Running scripts that require client cedentials
 
-To successfully run scripts that require client credentials, you will need to follow these steps:
-  1. Copy the contents of the `env.example` file in the script's directory to `.env`:
-        ```
-        cp env.example .env
-        ```
-  2. Uncomment the variables in the `.env` file and assign values as needed. See [`sources.md`](sources.md) on how to get credentials:
-        ```
-        GOOGLE_API_KEYS=your_api_key
-        PSE_KEY=your_pse_key
-       ```
-  3. Save the changes to the `.env` file.
+To successfully run scripts that require client credentials, you will need to
+follow these steps:
+1. Copy the contents of the `env.example` file in the script's directory to
+   `.env`:
+    ```shell
+    cp env.example .env
+    ```
+2. Uncomment the variables in the `.env` file and assign values as needed. See
+   [`sources.md`](sources.md) on how to get credentials:
+    ```
+    GOOGLE_API_KEYS=your_api_key
+    PSE_KEY=your_pse_key
+    ```
+3. Save the changes to the `.env` file.
+4. You should now be able to run scripts that require client credentials
+   without any issues.
+
+
+### Static analysis
 
-  4. You should now be able to run scripts that require client credentials without any issues.
+The `dev/tools.sh` helper script runs the static analysis tools:
+```shell
+./dev/tools.sh
+```
 
 
-### Tooling
+### Resources
 
 - **[Python Guidelines — Creative Commons Open Source][ccospyguide]**
-- [Black][black]: the uncompromising Python code formatter
-- [flake8][flake8]: a python tool that glues together pep8, pyflakes, mccabe,
-  and third-party plugins to check the style and quality of some python code.
-- [isort][isort]: A Python utility / library to sort imports
+- [Black][black]: _the uncompromising Python code formatter_
+- [flake8][flake8]: _a python tool that glues together pep8, pyflakes, mccabe,
+  and third-party plugins to check the style and quality of some python code._
+- [isort][isort]: _A Python utility / library to sort imports_
   - (It doesn't import any libraries, it only sorts and formats them.)
+- [ppypa/pipenv][pipenv]: _Python Development Workflow for Humans._
 
 [ccospyguide]: https://opensource.creativecommons.org/contributing-code/python-guidelines/
 [black]: https://github.com/psf/black
 [flake8]: https://gitlab.com/pycqa/flake8
 [isort]: https://pycqa.github.io/isort/
+[pipenv]: https://github.com/pypa/pipenv
 
 
-## Data Sources
+## Data sources
 
 Kindly visit the [`sources.md`](sources.md) file for it.
 
@@ -99,12 +109,13 @@ Kindly visit the [`sources.md`](sources.md) file for it.
 For information on past efforts, see [`history.md`](history.md).
 
 
-## Copying & License
+## Copying & license
 
 
 ### Code
 
-[`LICENSE`](LICENSE): the code within this repository is licensed under the Expat/[MIT][mit] license.
+[`LICENSE`](LICENSE): the code within this repository is licensed under the
+Expat/[MIT][mit] license.
 
 [mit]: http://www.opensource.org/licenses/MIT "The MIT License | Open Source Initiative"
 

From ebaa1cd585cd3bd7297c36ed9ff2e84d12ceb8ff Mon Sep 17 00:00:00 2001
From: Timid Robot Zehta <timid@creativecommons.org>
Date: Thu, 26 Oct 2023 13:24:15 -0700
Subject: [PATCH 2/2] fix list indentation

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c6addb6e..7f9fbfb0 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ modules:
         ```shell
         brew install pipenv
         ```
-  - Windows: [Installing Pipenv][pipenvinstall]
+   - Windows: [Installing Pipenv][pipenvinstall]
 2. Create the Python virtual environment and install prerequisites using
    `pipenv`:
     ```shell