Redo attempt 1

CONTRIBUTING.md

@@ -83,7 +83,7 @@ The actual process:
 - We create a new stage-main branch at least twice a month:
   - The stage-main branch includes the latest approved pull requests in one merged branch
     - This ensures that PRs will not contain anything that breaks deployment and also will allow us to see if any PRs negatively interact with each other before they end up merged to main. Why bother with this step? It's helpful to have a separate "release candidate" on the stage-main branch because in earlier testing rounds people weren't sure what had been deployed to staging and having a separate branch makes this explicit and clear.
-  - After stage-main is created, we deploy it to MoveOn's staging instance. We have a small set of QA volunteers who then run through a list of [QA steps](https://github.com/MoveOnOrg/Spoke/blob/main/docs/QA_GUIDE.md) in order to find bugs and test new features.
+  - After stage-main is created, we deploy it to MoveOn's staging instance. We have a small set of QA volunteers who then run through a list of [QA steps](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_QA_GUIDE.md) in order to find bugs and test new features.
   - After QA is completed, and volunteers haven't identified any bugs, we deploy stage-main to production.
   - We let stage-main run in production for at least a day, before merging stage-main into the main branch.
   - We never roll code directly to prod without first testing on staging.

README.md

@@ -14,9 +14,9 @@ The latest version is [8.1](https://github.com/MoveOnOrg/Spoke/tree/v8.1) (see [
 ## Get Started
 
 
-The easiest way to get started is with Heroku.  You can also learn about Spoke through the [texter](https://youtu.be/EqE1UDvKGco) and [admin](https://youtu.be/PTMykMX8gII) video demos or in the explanation on [how to decide if Spoke is right for you.](/EXPLANATION_DECIDING_ON_SPOKE.md)
+The easiest way to get started is with Heroku.  You can also learn about Spoke through the [texter](https://youtu.be/EqE1UDvKGco) and [admin](https://youtu.be/PTMykMX8gII) video demos or in the explanation on [how to decide if Spoke is right for you.](/docs/EXPLANATION_DECIDING_ON_SPOKE.md)
 
-For developers, please see our recomendations for [deploying locally for development](/HOWTO_DEVELOPMENT_LOCAL_SETUP.md).
+For developers, please see our recomendations for [deploying locally for development](/docs/HOWTO_DEVELOPMENT_LOCAL_SETUP.md).
 
 
 
@@ -28,7 +28,7 @@ This version of Spoke suitable for testing and, potentially, for small campaigns
   <img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy">
 </a>
 
-Follow up instructions located [here](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_HEROKU_DEPLOY.md).
+Follow up instructions located [here](/docs/HOWTO_HEROKU_DEPLOY.md).
 
 
 **NOTE:** You can upgrade this deployment later for use in a production (aka large-scale) setting, but keep in mind you will lose the data from any prior campaigns.  Thus it is best to upgrade before you start any live campaigns.  This will cost $75 ($25 dyno + $50 postgres) a month and should be suitable for production level usage for most organizations. Alternatively, you can click [this link to deploy with a production infrastructure from the start!](https://heroku.com/deploy?template=https://github.com/MoveOnOrg/Spoke/tree/heroku-button-paid) 
@@ -38,11 +38,11 @@ Please let us know if you deployed by filling out this form [here](https://act.m
 
 ## Other Options for Production Use 
 
-You can also [deploy on AWS Lambda.](https://github.com/MoveOnOrg/Spoke/blob/main/docs/DEPLOYING_AWS_LAMBDA.md) 
+You can also [deploy on AWS Lambda.](/docs/HOWTO_DEPLOYING_AWS_LAMBDA.md) 
 
 Additional guidance:
-- [Choosing a set-up for production](/EXPLANATION_CHOOSE_A_SETUP.md)
-- [How to hire someone to install Spoke](/HOWTO_HIRE_SOMEONE_TO_INSTALL_SPOKE.md)
+- [Choosing a set-up for production](/docs/EXPLANATION_CHOOSE_A_SETUP.md)
+- [How to hire someone to install Spoke](/docs/HOWTO_HIRE_SOMEONE_TO_INSTALL_SPOKE.md)
 
 
 ## More Documentation

docs/EXPLANATION-development-guidelines.md

@@ -37,7 +37,7 @@ diverse group of organizations and deployment contexts, which means a lot of con
 Some important places to update or consider updating when you are creating a new
 environment variable:
 
-* Documentation: Be sure to update or add your variable to [REFERENCE-environment_variables.md](./REFERENCE-environment_variables.md)
+* Documentation: Be sure to update or add your variable to [REFERENCE-environment_variables.md](/REFERENCE-environment_variables.md)
 * Make sure the default value will not break the application for users that upgrade from a context before the variable existed.
 * Only add to `.env.example` if it's an important variable to know about (e.g. the default value will often be wrong) or the development value will often be different (e.g. a DEBUG_ type variable)
 * `src/server/middleware/render-index.js` is important to update if this variable is needed on the client/React side and can't/shouldn't be sent through a GraphQL api/object.  In this case, see the bottom of that file.  Be careful since you are printing the variable in *raw javascript* -- so include a `|| <default>` value within the `${...}` context.
@@ -127,7 +127,7 @@ If you want to use the knex CLI, run with `yarn knex` which will leverage your `
 
 ## Apollo/GraphQL structure and gotchas
 
-See [EXPLANATION-request-example.md](./EXPLANATION-request-example.md) for a great run-down all the
+See [EXPLANATION-request-example.md](/EXPLANATION-request-example.md) for a great run-down all the
 way through the call stack on the client and server.
 
 See the [Apollo documentation](https://www.apollographql.com/docs/react/v2.5) for more details.

docs/EXPLANATION_CHOOSE_A_SETUP.md

@@ -14,9 +14,9 @@ Reasons to be ok with less control:
 
 There are many ways to deploy software onto hardware and many cloud computing providers. In this set of documentation, we use Heroku and Amazon AWS. AWS is more work to setup than Heroku, but gives you more control over scaling and security. In our experience, a full stack engineer with 2+ yrs experience that includes AWS can set this up in 5 days. There is also a Spoke open source community anchored in the Progressive Coders Network slack who can help with setup.
 
-If you're ok with less control, you can follow the instructions [here](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_HEROKU_DEPLOY.md) to deploy an instance of Spoke to Heroku  
+If you're ok with less control, you can follow the instructions [here](/HOWTO_HEROKU_DEPLOY.md) to deploy an instance of Spoke to Heroku  
 
-If you want more control, you can follow the instructions [here](https://github.com/MoveOnOrg/Spoke/blob/main/docs/DEPLOYING_AWS_LAMBDA.md) to deploy an instance of Spoke onto Amazon AWS. Many people use dedicated EC2 servers for deployment, but we've found lambda (pay-per-invocation vs hour) to be more cost effective for bursty traffic.
+If you want more control, you can follow the instructions [here](/HOWTO_DEPLOYING_AWS_LAMBDA.md) to deploy an instance of Spoke onto Amazon AWS. Many people use dedicated EC2 servers for deployment, but we've found lambda (pay-per-invocation vs hour) to be more cost effective for bursty traffic.
 
 
 ## What else do I need to worry about?

docs/HOWTO-use-action-handlers.md

@@ -12,10 +12,10 @@ implement them.
 Spoke includes several action handlers that integrate Spoke with some common
 external systems:
 
-- [ActionKit](docs/HOWTO_INTEGRATE_WITH_ACTIONKIT.md)
-- [Mobile Commons](docs/HOWTO_INTEGRATE_WITH_MOBILE_COMMONS.md)
+- [ActionKit](/HOWTO_INTEGRATE_WITH_ACTIONKIT.md)
+- [Mobile Commons](/HOWTO_INTEGRATE_WITH_MOBILE_COMMONS.md)
 - NGPVAN and everyaction ***(coming soon)***
-- [Revere](ocs/HOWTO_INTEGRATE_WITH_REVERE.md)
+- [Revere](/HOWTO_INTEGRATE_WITH_REVERE.md)
 
 In addition, there are two action handlers that don't do much, but they serve
 as reference implementations:

docs/HOWTO_BUY_NUMBERS_IN_TWILIO.md

@@ -1,6 +1,6 @@
 # How to Buy Numbers in Twilio
 
-This guide assumes you already have twilio set up with Spoke. If you don't, check out our guide on [integrating Twilio](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_INTEGRATE_TWILIO.md).
+This guide assumes you already have twilio set up with Spoke. If you don't, check out our guide on [integrating Twilio](/HOWTO_INTEGRATE_TWILIO.md).
 
 If you are comfortable using the Linux command line, and/or will be buying many numbers across many area codes, you should take a look at the [switchboard-twilio tool](https://github.com/MoveOnOrg/switchboard-twilio) which is here to help you buy in higher quantities.
 
@@ -10,7 +10,7 @@ If you are comfortable using the Linux command line, and/or will be buying many
    ![sms menu](images/twilio_number_buying_guide/sms_menu.png "SMS Menu")
 3. Select "Messaging Services"
    ![messaging services](images/twilio_number_buying_guide/messaging_services.png "SMS Menu")
-4. Click the app on this screen that's corresponding to whatever you chose when you created the [Spoke messaging service in step 5 here](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_INTEGRATE_TWILIO.md) - You should see a sub menu with "numbers", "features", "settings"
+4. Click the app on this screen that's corresponding to whatever you chose when you created the [Spoke messaging service in step 5 here](/HOWTO_INTEGRATE_TWILIO.md) - You should see a sub menu with "numbers", "features", "settings"
    ![spoke app name](images/twilio_number_buying_guide/spoke_app_name.png "Click your app")
 5. Click numbers
    ![numbers menu](images/twilio_number_buying_guide/numbers_menu.png "Numbers Menu")

docs/HOWTO_CODE_REVIEW.md

@@ -1,15 +1,15 @@
 # How to Code Review
 Thank you for stepping up to code review changes for Spoke! Check out [our developer docs](https://github.com/MoveOnOrg/Spoke#more-documentation) for more information about how we write code.
 ## Pre-Review
-- Put your mentor hat on — be respectful and gentle — the Spoke project encourages contributions from beginner-developers, and we want to make their early experiences with open-source contributions as positive as possible. We have a [Code of Conduct](https://github.com/MoveOnOrg/Spoke/blob/main/CODE_OF_CONDUCT.md) that we expect all members of the community to follow, and is especially important in the position of being a reviewer.
+- Put your mentor hat on — be respectful and gentle — the Spoke project encourages contributions from beginner-developers, and we want to make their early experiences with open-source contributions as positive as possible. We have a [Code of Conduct](./CODE_OF_CONDUCT.md) that we expect all members of the community to follow, and is especially important in the position of being a reviewer.
 
-- If you are unable to complete a review that you’re tagged in within a [48 hour window](https://github.com/MoveOnOrg/Spoke/new/main/docs#why-review-quickly), comment to let us know and reassign to another reviewer. For large pull requests that will take longer to review, please comment on the issue with a deadline for yourself to complete the review.
+- If you are unable to complete a review that you’re tagged in within a [48 hour window](#why-review-quickly), comment to let us know and reassign to another reviewer. For large pull requests that will take longer to review, please comment on the issue with a deadline for yourself to complete the review.
 
 - Check the automatically deployed heroku instance and ensure that the change is present and operates as expected.
 
 ## The Review
 
-- Look for blocking characteristics in the code. As you identify what you want to comment on remember to use [kind language and to critique the code rather than the author](https://github.com/MoveOnOrg/Spoke/new/main/docs#critique-the-code-not-the-author). We’re all a team and we want to affirm the efforts of people contributing. <sup>1</sup>
+- Look for blocking characteristics in the code. As you identify what you want to comment on remember to use [kind language and to critique the code rather than the author](#critique-the-code-not-the-author). We’re all a team and we want to affirm the efforts of people contributing. <sup>1</sup>
 
   - **Functional issues:** Does the code have any bugs in it? Does it do what it says it does? Does it break anything existing?
   - **Edge cases that aren’t covered:** Did the author miss any conditions or use cases?

docs/HOWTO_DATA_EXPORTING.md

@@ -17,7 +17,7 @@ To use Bucketeer, [skip to the end of this document](#bucketeer-setup).
 ## S3 setup
 
 __Skip this section__ if you are using Bucketeer.
-  1. __[Configure Spoke to send emails](EMAIL_CONFIGURATION.md).__
+  1. __[Configure Spoke to send emails](HOWTO_EMAIL_CONFIGURATION.md).__
   2. __Create an AWS account.__ If you already have an AWS account, skip this step. Otherwise, see [Amazon's documentation](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) to create an AWS account.
   3. __Sign up for S3.__ If you already have S3, skip this step. Otherwise, see [Amazon's documentation](https://docs.aws.amazon.com/AmazonS3/latest/gsg/SigningUpforS3.html) to sign up for S3 using your AWS account.
   4. __Create a S3 bucket.__ If you already have an S3 bucket, skip this step. Otherwise, see [Amazon's documentation](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) to create an S3 bucket. You __don't__ need to enable public access to the bucket.

docs/HOWTO_DEVELOPMENT_LOCAL_SETUP.md

@@ -27,7 +27,7 @@ The following is the reccomended developer set-up.  If you prefer, [click here f
 
 ### Your `.env` file
 
-We use environment variables to allow instance admins to customize their Spoke experience. If you end up doing dev work on an area that is configured through environment variables, it will be helpful to be familiar with the patterns used. Because of this, we recommend that you take a look at the [environment variable reference](https://github.com/MoveOnOrg/Spoke/blob/main/docs/REFERENCE-environment_variables.md) to get a lay of the land.  
+We use environment variables to allow instance admins to customize their Spoke experience. If you end up doing dev work on an area that is configured through environment variables, it will be helpful to be familiar with the patterns used. Because of this, we recommend that you take a look at the [environment variable reference](REFERENCE-environment_variables.md) to get a lay of the land.  
 
 ### Your Database
 
@@ -38,7 +38,7 @@ If you're using postgres (see below), you should set `DB_TYPE=pg` and if you're
 
 #### Using Docker to run postgres (optional)
 
-Docker is optional, but can help with a consistent development environment using postgres. You can also set up postgres without docker ([documented here](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO_USE_POSTGRESQL.md)) but we recommend the docker route.
+Docker is optional, but can help with a consistent development environment using postgres. You can also set up postgres without docker ([documented here](HOWTO_USE_POSTGRESQL.md)) but we recommend the docker route.
 
 1. Install docker and docker compose
 
@@ -68,8 +68,8 @@ At this point, you should be ready to start your app in development mode.
 4. You should then be prompted to create an organization. Create it.
 5. Once you've created your organization, we recommend setting the env var `SUPPRESS_SELF_INVITE=1` so you don't get prompted to create a new org every time you log in
 6. See the [Admin](https://youtu.be/PTMykMX8gII) and [Texter](https://youtu.be/EqE1UDvKGco) demos to learn about how Spoke works.
-7. See [Getting Started with Development](#more-documentation) below.
-8. See [How to Run Tests](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO-run_tests.md)
+7. See [the development guidelines](EXPLANATION-development-guidelines.md)
+8. See [How to Run Tests](HOWTO-run_tests.md)
 
 ### SMS and Twilio in development
 

docs/HOWTO_HEROKU_DEPLOY.md

@@ -11,7 +11,7 @@
 
 ## Instructions for Auth0 configuration variable setup
 
-- Follow the instructions at [Auth0 for authentication](https://github.com/MoveOnOrg/Spoke/blob/main/docs/HOWTO-configure-auth0.md)
+- Follow the instructions at [Auth0 for authentication](HOWTO-configure-auth0.md)
   - Where the instructions mention `yourspoke.example.com`, replace it with `<YOUR SPOKE APP>.herokuapp.com` (or in production, possibly the domain you aliased to it in your DNS config)
 
 
@@ -57,11 +57,11 @@ There is another mode mostly for non-Twilio backends, where you may need to run
 
 ## Email configuration
 
-See [this guide](EMAIL_CONFIGURATION.md) for instructions.
+See [this guide](HOWTO_EMAIL_CONFIGURATION.md) for instructions.
 
 ## Data exporting
 
-In order to export data from campaigns (such as contacts' responses to questions), you need to configure S3 or Bucketeer. See [this guide](DATA_EXPORTING.md) for instructions.
+In order to export data from campaigns (such as contacts' responses to questions), you need to configure S3 or Bucketeer. See [this guide](HOWTO_DATA_EXPORTING.md) for instructions.
 
 ## Upgrading an existing Heroku app