Apply suggestions from review by @lkasso

Co-authored-by: Laura Kassovic <[email protected]>

docs/CONTRIBUTING.md

@@ -3,15 +3,16 @@
 [![a](https://img.shields.io/badge/slack-%23docs-brightgreen?style=flat&logo=slack)](./contributing/community-slack.md)
 
 Contributing to this site is easy!
-We do not have so many newcomer friendly issues in this repository,
-but you are welcome to submit any small and big patches!
+While we may not have many issues for newcomers,
+we welcome all contributions, big or small. 
 
-Many smaller changes can be done from a browser.
+Many minor changes can be made directly from your browser.
 Just submit a pull request to the respective repository.
 On the rop right corner you can also see the _Edit_ icons
 that will normally get you right to the content page.
 
-For bigger changes, you can do the development locally, and it is documented below.
+For bigger changes, you can develop locally. 
+Detailed instructions are provided below.
 
 ## Communication channels
 
@@ -25,15 +26,15 @@ See the [Gradle Cookbook Contributor Guide](./cookbook/CONTRIBUTING.md).
 
 ### Other locations
 
-The Gradle website is at the early stages of development,
-and we do not have a fixed process and practices.
-Just submit a pull request with a change.
-Should youhave any concerns, let's discuss it on Slack or a GitHub issue.
+The Gradle website is in the early stages of development,
+and we do not have fixed processes and practices yet.
+Just submit a pull request with your change.
+If you have any concerns, let's discuss them on Slack or in a GitHub issue.
 
 ## Developing the site
 
 It is possible to deploy the site instance locally or inside a Dev Container.
-The latter is a recommended approach.
+The latter is the recommended approach.
 
 ### Technology under the hood
 
@@ -43,13 +44,13 @@ and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).
 So, it uses the Python technology stack instead of Gradle,
 but on the other hand we're leveraging one of the most powerful documentation engines.
 
-### Setting iup the environment
+### Setting up the environment
 
 #### Dev Containers
 
 This repository includes the Dev Container definition that you can use in Visual Studio Code or in IntelliJ Platform
 to spin up the local development environment.
-The same Dev Container is used for CI/CD, and it is a recommended way of local development,
+The same Dev Container is used for CI/CD, and it is the recommended way for local development.
 
 #### Running locally
 

docs/contributing/documentation/README.md

@@ -31,8 +31,8 @@ All contributions are welcome!
 
 In Gradle we use a diverse set of tooling for documentation development.
 We use both Markdown and Asciidoc for writing,
-with MkDocs, Jekyll and Gradle Asciidoc Plugin being our main tools for documentation.
-We also use other tools like Dokka, Javadoc, OpenAPI specifications, etc.
+with MkDocs, Jekyll, and the Gradle Asciidoc Plugin as our main tools for documentation.
+Additionally, we utilize other tools such as Dokka, Javadoc, and OpenAPI specifications.
 
 Many small patches can be just submitted from the GitHub web editor.
 For bigger patches and local development, see the referenced contributing guidelines.

docs/cookbook/CONTRIBUTING.md

@@ -17,17 +17,17 @@ Any contributions are welcome!
 
 A few tips:
 
-- All the pages on this site are just Markdown
+- All the pages on this site are written in Markdown.
 - If needed, we can a lot of machineryy reserved, e.g. for including code templates, macros, etc.
   And we can add more MkDocs plugins if needed.
 - The Table of Contents is currently located in [mkdocs.yml](../mkdocs.yml).
-  When adding new pages, please update the ToC so that it is discoverable.
+When adding new pages, please update the ToC to ensure they are discoverable.
 
 ### Adding New Categories
 
-At the moment, we just add categories as convenient based opn the consensus.
-If you add a new major category, better to discuss it in advance.
+At the moment, we add categories based on consensus.
+If you plan to add a new major category, it's better to discuss it in advance.
 
 ## References
 
-- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute in general, and how to set up the local environment if needed
+- [Main community.gradle.org contributor guide](../CONTRIBUTING.md) - describes how to contribute and how to set up the local environment if needed

docs/cookbook/README.md

@@ -26,14 +26,14 @@ The Gradle Build Tool ecosystem is huge, it includes many plugins, integrations,
 Not all of them can be covered in the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html)
 which represents core documentation maintained for each Gradle release.
 Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there.
-Even for us, it has been difficult to maintain documentation in such a way,
-and many pages have been quite outdated.
+Maintaining documentation has been challenging for us as well,
+leading to many outdated pages.
 
 So, we decided to build a second resource as an extension to the Gradle User Manual,
 with the following in mind:
 
 - Gradle Cookbook remains an official resource under `community.gradle.org`.
-  It is not a second-class citizen, just another structure not tied to the Gradle release cycle
+  It is not a second-class citizen, just another structure that is not tied to the Gradle release cycle
 - Pages should be focused on offering solutions to end users for particular use cases,
   hence the _Cookbook_
 - We follow the Wiki-alike collaboration style,