diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 86ee7fb67d1..601f5094dcc 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -7,10 +7,10 @@ To help us review it efficiently, please ensure you've gone through the followin
 - [ ] I have updated existing examples or added new ones (if applicable).
 - [ ] I have used `cargo xtask fmt-packages` command to ensure that all changed code is formatted correctly.
 - [ ] My changes were added to the [`CHANGELOG.md`](https://github.com/esp-rs/esp-hal/blob/main/esp-hal/CHANGELOG.md) in the **_proper_** section.
-- [ ] My changes are in accordance to the [esp-rs API guidelines](https://github.com/esp-rs/esp-hal/blob/main/API-GUIDELINES.md)
+- [ ] My changes are in accordance to the [esp-rs API guidelines](https://github.com/esp-rs/esp-hal/blob/main/documentation/API-GUIDELINES.md)
 
 #### Extra:
-- [ ] I have read the [CONTRIBUTING.md guide](https://github.com/esp-rs/esp-hal/blob/main/CONTRIBUTING.md) and followed its instructions.
+- [ ] I have read the [CONTRIBUTING.md guide](https://github.com/esp-rs/esp-hal/blob/main/documentation/CONTRIBUTING.md) and followed its instructions.
 
 ### Pull Request Details 📖
 
diff --git a/README.md b/README.md
index f78c7771323..aa4c7c319c9 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ If you have any questions, comments, or concerns, please [open an issue], [start
 
 > [!NOTE]
 >
-> This project is still in the relatively early stages of development, and as such there should be no expectation of API stability. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most basic tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented.
+> This project is still in the relatively early stages of development, and as such there should be no expectation of API stability. A significant number of peripherals currently have drivers implemented but have varying levels of functionality. For most tasks, this should be usable already, however some more advanced or uncommon features may not yet be implemented.
 
 [esp-lp-hal]: https://github.com/esp-rs/esp-hal/tree/main/esp-lp-hal
 [esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc
@@ -49,6 +49,13 @@ For information about the HAL and how to use it in your own projects, please ref
 
 This repository is home to a number of different packages; for more information regarding a particular package, please refer to its `README.md` and/or documentation.
 
+## Contributing
+
+We have a number of living documents to aid contributing to the project, please give these a read before modifying code:
+
+- [API-GUIDELINES](https://github.com/esp-rs/esp-hal/blob/main/documentation/API-GUIDELINES.md)
+- [CONTRIBUTING-GUIDE](https://github.com/esp-rs/esp-hal/blob/main/documentation/CONTRIBUTING.md)
+
 ## License
 
 Licensed under either of:
@@ -58,10 +65,8 @@ Licensed under either of:
 
 at your option.
 
-### Contribution
+### Contribution notice
 
 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in
 the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without
 any additional terms or conditions.
-
-If you consider contributing, please make sure you have read and understood our [contributing guide](./CONTRIBUTING.md) and [API guidelines](https://github.com/esp-rs/esp-hal/blob/main/API-GUIDELINES.md).
diff --git a/API-GUIDELINES.md b/documentation/API-GUIDELINES.md
similarity index 100%
rename from API-GUIDELINES.md
rename to documentation/API-GUIDELINES.md
diff --git a/CONTRIBUTING.md b/documentation/CONTRIBUTING.md
similarity index 99%
rename from CONTRIBUTING.md
rename to documentation/CONTRIBUTING.md
index d0c009718b0..e0abb806e07 100644
--- a/CONTRIBUTING.md
+++ b/documentation/CONTRIBUTING.md
@@ -41,7 +41,7 @@ Before adding or changing code, review the [esp-rs API guidelines].
 [Setting Up Git]: https://docs.github.com/en/get-started/quickstart/set-up-git
 [GitHub Flow]: https://docs.github.com/en/get-started/quickstart/github-flow
 [Pull Requests]: https://docs.github.com/en/github/collaborating-with-pull-requests
-[esp-rs API guidelines]: ./API-GUIDELINES.md
+[esp-rs API guidelines]: ./documentation/API-GUIDELINES.md
 
 ## Getting Started