Improve README

This is a proposal for a greatly improved README.md.

Author: nadimkobeissi

README.md

@@ -1,61 +1,82 @@
-# Polygon docs
+# Polygon Technical Docs
 
-Welcome to the Polygon Docs website, built with [the Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+Welcome to the Polygon Technical Docs! This documentation is built using [the Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/). Our goal is to establish a high-quality, curated, and comprehensive "source of truth" for technical knowledge surrounding Polygon's main technology. This includes detailed sections on:
 
-## Instructions for use
+- Polygon CDK
+- Polygon zkEVM
+- Polygon PoS
+- Polygon Miden
 
-Work on a local branch and request a review from a teammate.
+In addition, we include top-level sections for Tools and Tutorials to support developers in their journey with Polygon technology.
 
-## How to run the site locally
+## Contributing
 
-### Clone the repo
+### Getting started
 
-```sh
-git clone https://github.com/0xPolygon/polygon-docs.git
-cd polygon-docs
-```
+1. **Fork and Branch**: Fork the `main` branch into your own GitHub account. Create a feature branch for your changes.
+2. **Make Changes**: Implement your changes or additions in your feature branch.
+3. **Contribution Quality**: Ensure that your contributions are:
+   - **Atomic**: Small, self-contained, logical updates are preferred.
+   - **Well Documented**: Use clear commit messages. Explain your changes in the pull request description.
+   - **Tested**: Verify your changes do not break existing functionality.
+   - **Styled Correctly**: Follow the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
 
-### Run with Python
+### Creating a pull request
 
-1. Download and install Python 3.11: https://www.python.org/downloads/
+1. **Pull Request**: Once your changes are complete, create a pull request against the main branch of Polygon Technical Docs.
+2. **Review Process**: Your pull request will be reviewed by the maintainers. They may request changes or clarifications.
+3. **Responsibility**: Contributors are expected to maintain their contributions over time and update them as necessary to ensure continued accuracy and relevance.
 
-2. Install the `virtualenv` package:
+### Best practices
 
-```sh
-pip install virtualenv
-```
+- **Stay Informed**: Keep up-to-date with the latest developments in Polygon technologies.
+- **Engage with the Community**: Participate in discussions and provide feedback on other contributions.
+- **Stay Consistent**: Ensure your contributions are coherent with the rest of the documentation and do not overlap or contradict existing content.
 
-3. Build and serve the html
 
-```sh
-./run.sh
-```
+## Running locally
+
+### Prerequisites
+
+Before running the site locally, you need to have the following installed:
 
-The site runs at: http://127.0.0.1:8000/
+1. [Python 3](https://www.python.org/downloads/).
+2. [`virtualenv`](https://pypi.org/project/virtualenv/): Install using `pip3 install virtualenv`.
 
-### Run with Docker
+### Setup
 
-1. Run the following commands from the project root:
+1. **Clone Repository**: Clone the Polygon Technical Docs repository to your local machine.
+2. **Create a Virtual Environment**: Run `virtualenv venv; source venv/bin/activate` in the root directory.
+3. **Install Dependencies**: Install required Python packages with `pip3 install -r requirements.txt`.
+
+### Running the Website
+
+1. **MkDocs in Strict Mode**: Use `mkdocs serve --strict` for a production-like environment.
+2. **MkDocs in Normal Mode**: Use `mkdocs serve` for a less strict, more forgiving environment, suitable for debugging.
+
+### Docker Alternative
+
+If you prefer Docker, you can build and run the site using the following commands:
 
 ```sh
 docker build -t polygon-docs .
 docker compose up
 ```
 
-### Run manually
+## Automated deployments
 
-1. Download and install Python, as above, and ensure you have installed all the packages listed in `requirements.txt`, e.g.:
+This repository uses GitHub Actions to automate some deployments from certain branches, which is useful for testing:
 
-```sh
-pip install markdown-include==0.8.1
-```
+- **`main`**: Staging branch. Changes are deployed per-commit to https://docs-staging.polygon.technology.
+- **`dev`**: Experimental branch. Updates with main every 24 hours. Changes are deployed per-commit to https://docs-dev.polygon.technology.
 
-2. Run the following from the project root to bring up the site:
+Whenever we are happy with `main`, a trigger can be manually done through GitHub Actions which deploys staging to production at https://docs.polygon.technology.
 
-```sh
-mkdocs serve --strict
-```
+## Contact and support
 
-## Questions
+For any queries or support, join our Polygon Slack channel at `#disc_tkd_techdocs`. Current team members:
 
-Feel free to contact the team any time: `#disc_tkd_techdocs`
+- Nadim Kobeissi (@nadimkobeissi)
+- Anthony Matlala (@EmpieichO)
+- Katharine Murphy (@kmurphypolygon)
+- Grace Torrellas (@0xgraciegrace)