merge: #3979

3979: Centralize and modernize all documentation (ENG-2580) r=nickgerace a=nickgerace

## Description

This PR centralizes and modernizes all documentation. The goal for this centralized document is to provide a nexus for notes and long-living documentation for using and developing the System Initiative software.

The centralized document does not strive to contain feature-specific documentation as the product is ever changing. It is simply designed as a hub for bucketed information that needs a home (e.g. "do not run SI on a toaster, please").

The new documentation format takes advantage of GitHub markdown rendering.

All section and pathing lookups have been modified as a result of these changes.

## Demo

- [Click here to see the rendered version](https://github.com/systeminit/si/blob/a62d626d0b0afd61eeb95ce63e8964298d54b812/DOCS.md)
- [Click here to see the README that has changed as a result](https://github.com/systeminit/si/blob/a62d626d0b0afd61eeb95ce63e8964298d54b812/README.md)

Co-authored-by: Nick Gerace <[email protected]>

CODE_OF_CONDUCT.md

@@ -34,4 +34,4 @@ And if someone takes issue with something you said or did, resist the urge to be
 
 The enforcement policies listed above apply to all official System Initiative venues; including [Discord channels](https://discord.com/invite/system-init), all repositories owned by this GitHub organization, and all other public mediums.
 
-_Adapted from the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct)_
+_Adapted from the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct)_

CONTRIBUTING.md

@@ -37,11 +37,11 @@ If you are looking to make a substantial, complex, or wide-sweeping contribution
 Follow the following steps to ensure your contribution goes smoothly.
 
 1. Read and follow the steps outlined in the [System Initiative Contributing Policy](README.md#contributing).
-1. Configure your development environment by either following the guide in the [README](README.md) or the [full documentation](docs/DEVELOPMENT_ENVIRONMENT.md).
+1. Configure your development environment by either following the guide in the [README](README.md) or the [full documentation](DOCS.md).
 1. [Fork](https://help.github.com/articles/working-with-forks/) the GitHub Repository allowing you to make the changes in your own copy of the repository.
 1. Create a [GitHub issue](https://github.com/systeminit/si/issues) if one doesn't exist already.
-1. Make the changes you would like to include, adding new tests where possible, and make sure all relevant existing [tests are passing](docs/RUNNING_RUST_TESTS.md).
-1. [Prepare your changes](/docs/PREPARING_YOUR_CHANGES.md) and ensure your commits are descriptive. The document contains an optional commit template, if desired.
+1. Make the changes you would like to include, adding new tests where possible, and make sure all relevant existing [tests are passing by using the guide in our docs](DOCS.md).
+1. [Prepare your changes by checking out the relevant section in our docs](DOCS.md) and ensure your commits are descriptive. The document contains an optional commit template, if desired.
 1. Ensure that you are in the [CONTRIBUTORS](CONTRIBUTORS.md) file (see the [Adding Yourself to the Contributors List](#adding-yourself-to-the-contributors-list) section for instructions)
 1. Create a pull request on GitHub. If you're new to GitHub, read about [pull requests](https://help.github.com/articles/about-pull-requests/). You are welcome to submit your pull request for commentary or review before it is complete by creating a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests). Please include specific questions or items you'd like feedback on.
 1. A member of the System Initiative team will review your PR within three business days (excluding holidays in the USA, Canada, UK, and Brazil) and either merge, comment, and/or assign someone for review.
@@ -128,4 +128,4 @@ Here is an example:
 chore: add nickgerace to contributors
 ```
 
-After the commit is pushed, you should be good to go!
+After the commit is pushed, you should be good to go!

README.md

@@ -18,9 +18,8 @@ We are working on and investigating more way(s) to try out System Initiative in
 
 ## Local Development Setup
 
-Running the System Initiative software locally can be done in a variety of ways, but this abbreviated section will focus on a single method for
-getting your environment ready to run the stack.
-For more information and options on running SI locally, see the [development environment documentation](./docs/DEVELOPMENT_ENVIRONMENT.md).
+Running the System Initiative software locally can be done in a variety of ways, but this abbreviated section will focus on a single method for getting your environment ready to run the stack.
+For more information and options on running SI locally, see the [development environment section of the docs](DOCS.md).
 
 ### (1) Choose a Supported Platform
 
@@ -51,11 +50,10 @@ For `docker`, the Docker Desktop version corresponding to your native architectu
 WSL2 users should be able to use either Docker Desktop for WSL2 or Docker Engine inside the WSL2 VM.
 
 For `direnv`, you can install it with [your package manager of choice](https://direnv.net/docs/installation.html).
-However, if you're unsure which installation method to use or your package manager does not provide a compatible version,
-you can use `nix` itself (e.g. `nix profile install nixpkgs#direnv`).
+However, if you're unsure which installation method to use or your package manager does not provide a compatible version, you can use `nix` itself (e.g. `nix profile install nixpkgs#direnv`).
 
-> We recommend using [the upstream docs for hooking `direnv` into your shell](https://direnv.net/docs/hook.html), but here is an example on how to do it
-> on a system where `zsh` is the default shell.
+> [!TIP]
+> We recommend using [the upstream docs for hooking `direnv` into your shell](https://direnv.net/docs/hook.html), but here is an example on how to do it on a system where `zsh` is the default shell.
 > In this example, the following is added to the end of `~/.zshrc`.
 >
 > ```zsh
@@ -67,10 +65,10 @@ you can use `nix` itself (e.g. `nix profile install nixpkgs#direnv`).
 ### (3) Enter the Repository Directory
 
 All commands need to be run from the `nix` environment.
-Since `direnv` is installed _and_ hooked into your shell, you can `cd` into
-the repository and `nix` will bootstrap the environment for you using the flake.
+Since `direnv` is installed _and_ hooked into your shell, you can `cd` into the repository and `nix` will bootstrap the environment for you using the flake.
 
-_Please note: you may notice a large download of dependencies when entering the repository for the first time._
+> [!WARNING]
+> You may notice a large download of dependencies when entering the repository for the first time.
 
 ### (4) (Optional) Configure Docker
 
@@ -82,7 +80,7 @@ docker login
 
 ### (5) Running the Stack
 
-We use [**buck2**](https://github.com/facebook/buck2) to run the stack, run and build individual services and libraries, perform lints and tests, etc.
+We use [`buck2`](https://github.com/facebook/buck2) to run the stack, run and build individual services and libraries, perform lints and tests, etc.
 
 _Before continuing, you should stop any locally running services to avoid conflicting ports with the stack.
 Some of the services that will run include, but are not limited to the following: PostgreSQL, NATS, Jaeger and OpenTelemetry._
@@ -95,6 +93,7 @@ buck2 run dev:healthcheck
 
 You may notice some checks related to resource limits.
 On macOS and in WSL2 in particular, we recommend significantly increasing the file descriptor limit for `buck2` to work as intended (e.g. `ulimit -n 10240`).
+
 _Please note: the new file descriptor limit may not persist to future sessions._
 
 Once ready, we can build relevant services and run the entire stack locally.
@@ -109,10 +108,11 @@ buck2 run dev:up
 Once Tilt starts, you can check on the status of all services by accessing the UI through the given port on your local host (e.g. [http://localhost:10350/](http://localhost:10350/)).
 Every service should eventually have a green checkmark next to them, which ensures that they are in "ready" states.
 
-_Please note: database migrations may take some time to complete._
+> [!WARNING]
+> _Database migrations may take some time to complete._
 
-If you would like to learn more on what's running, check out the [services](./docs/SERVICES.md) documentation.
-If you would like to learn more about running the stack locally, check out the [development environment documentation](./docs/DEVELOPMENT_ENVIRONMENT.md) and the [documentation for running the stack locally](./docs/RUNNING_THE_STACK_LOCALLY.md).
+If you would like to learn more on what's running, check out the [docs](DOCS.md).
+In our documentation, you can also learn more about running the stack locally and a deeper dive into system requirements.
 
 ### (6) Troubleshooting in Tilt
 
@@ -140,7 +140,7 @@ buck2 run dev:stop
 ## Where Do I Learn More?
 
 For more information on how to use and develop the System Initiative software, talk to us on
-[our Discord](https://discord.com/invite/system-init) and see the [docs](./docs) directory.
+[our Discord](https://discord.com/invite/system-init) and see the [DOCS](DOCS.md).
 
 ## How Can I Contribute?