docs: reviewed monorepo content (#574)

* docs: reviewed type-safe-api topic

* docs: updated from feedback

* Minor fix to overview section

* docs: Using Smithy doc review

* docs: reviewed monorepo docs

---------

Co-authored-by: Jack Stevenson <[email protected]>

packages/monorepo/docs/developer_guides/monorepo/building.md

@@ -4,19 +4,19 @@
 
 Projen defines a standard way for building software through a fixed set of build phases. This is implemented via a set of tasks defined in the Project base class which all constructs extend from.
 
-The `build` task spawns a set of sub-tasks which represent the various build phases:
+The `build` task contains a set of sub-tasks which represent the various build phases:
 
-**default** - this task is responsible to execute your projenrc and synthesize all project files.
-**pre-compile** - runs before compilation (eg. bundle assets)
-**compile** - compile your code (if needed)
-**post-compile** - runs immediately after a successful compilation
-**test** - runs tests
-**package** - creates a distribution package
+- **default** - responsible for running your projenrc and synthesizing all project files.
+- **pre-compile** - runs before compilation (eg. bundle assets).
+- **compile** - compiles your code (if needed).
+- **post-compile** - runs immediately after a successful compilation.
+- **test** - runs tests.
+- **package** - creates a distribution package.
 
-To extend the build process, components and projects can use project.projectBuild.xxxTask and interact with the Task object (i.e. project.projectBuild.postCompileTask.exec("echo hi") will execute echo hi after compilation).
+To extend the build process, components and projects can use `project.projectBuild.xxxTask` and interact with the Task object (for example, `project.projectBuild.postCompileTask.exec("echo hi")` will run `echo hi`` after compilation).
 
 !!!note
-    The build task itself is locked. This means that any attempt to extend it (i.e. call spawn, exec, reset, etc) will throw an exception Instead of extending build, just extend one of the phases. This ensures that phases are always executed in the right order.
+    The build task itself is locked. This means that any attempt to extend it (i.e. call spawn, exec, reset, etc) will throw an exception. We recommend just extend one of the phases instead of extending the build. This ensures that phases are always executed in the right order.
 
 _Sourced from: https://projen.io/build.html_
 
@@ -31,7 +31,7 @@ const helloTask = project.tasks.addTask("hello");
 helloTask.exec("echo world");
 ```
 
-After you synthesize this change, you will be able to call your task by executing `pdk hello`.
+After you synthesize this change, you can call your task by executing `pdk hello`.
 
 ### Changing a task
 
@@ -43,17 +43,17 @@ someTask.exec('echo something');
 someTask.spawn(someOtherTask);
 ```
 
-This will make the `<some-task>` task a no-op. You can then add your own steps by calling `exec/spawn` on the task
+This will make the `<some-task>` task a no-op. You can then add your own steps by calling `exec/spawn` on the task.
 
 !!!tip
-    The default phase tasks are available directly within the project as they always exist and can be reference like `project.compileTask`.
+    The default phase tasks are available directly within the project as they always exist and can be referenced like `project.compileTask`.
 
 ## Full build
 
-In order to perform a full build of your codebase, run the `pdk build` command from the root of your monorepo. This will build each of your projects in dependency order.
+In order to perform a full build of your codebase, run the `pdk build` command from the root of your monorepo. This will build each of your projects in the dependency order.
 
-The `pdk build` command is a convenience wrapper around an underlying `nx run-many --target=build --output-style=stream --nx-bail` command. As such you can pass in any options available in the [nx cli](https://nx.dev/packages/nx/documents/run-many) for example `pdk build --parallel=10` will perform the build with up to 10 parallel processes.
+The `pdk build` command is a convenience wrapper around an underlying `nx run-many --target=build --output-style=stream --nx-bail` command. You can pass in any options available in the [nx cli](https://nx.dev/packages/nx/documents/run-many), for example `pdk build --parallel=10` will perform the build with up to 10 parallel processes.
 
 ## Targeted build
 
-In order to perform a targeted build of a single package and it's dependencies, run the `pdk nx run <package-name>:build` command. This will build the `package-name` and all of it's dependencies in correct dependency order.
+In order to perform a targeted build of a single package and its dependencies, run the `pdk nx run <package-name>:build` command. This will build the `package-name` and all of its dependencies in the correct dependency order.

packages/monorepo/docs/developer_guides/monorepo/caching.md

@@ -1,16 +1,16 @@
 # Caching
 
-Whenever executing a build via the `pdk build` command (or any nx command), [NX](https://nx.dev/) (the underlying build system) will [cache your outputs](https://nx.dev/concepts/how-caching-works) so that subsequent builds which do not have any changes can simply be skipped and use cached results. It does this by generating a hash, based on an input set which typically comprises of:
+Whenever executing a build via the `pdk build` command (or any nx command), [NX](https://nx.dev/) (the underlying build system) will [cache your outputs](https://nx.dev/concepts/how-caching-works) so that subsequent builds which do not have any changes can be skipped and use cached results. It does this by generating a hash, based on an input set which typically comprises of:
 
 - All the source files of your package and its dependencies
 - Relevant global config
 - Versions of external dependencies
 - Runtime values passed in by the user
 - CLI flags
 
-After Nx computes the hash for a task, it then checks if it ran this exact computation before. First, it checks locally, and then if it is missing, and if a remote cache is configured, it checks remotely.
+After NX computes the hash for a task, it then checks if it ran this exact computation before. First, it checks locally, and then if it is missing, and if a remote cache is configured, it checks remotely.
 
-If Nx finds the computation, Nx retrieves it and replays it. Nx places the right files in the right folders and prints the terminal output. From the user’s point of view, the command ran the same, just a lot faster.
+If Nx finds the computation, it retrieves it and replays it. Nx places the right files in the right folders and prints the terminal output. From the user’s point of view, the command runs the same, just a lot faster.
 
 By default, all cached results are stored within either `.nx/cache` or `node_modules/.cache/nx`. The PDK uses sane defaults for which files to cache _i.e: build directory, cdk.out, etc_. There may be situations where certain input files or output files need to be adjusted. To do this, add the following to your `projenrc` file:
 

packages/monorepo/docs/developer_guides/monorepo/dependencies.md

@@ -2,21 +2,21 @@
 
 Dependencies are an intrinsic part of every software project.
 
-The Dependencies component is responsible to track the list of dependencies a project has, and then used by project types as the model for rendering project-specific dependency manifests such as the dependencies section package.json, pom.xml or pyproject.toml files.
+The `Dependencies` component is responsible to track the list of dependencies a project has, and then used by project types as the model for rendering project-specific dependency manifests such as the dependencies section `package.json`, `pom.xml` or `pyproject.toml` files.
 
-To add a dependency, you can use a project-type specific API such as `nodeProject.addDeps()` or use the generic API of `project.deps`:
+To add a dependency, use a project-type specific API such as `nodeProject.addDeps()` or use the generic API `project.deps`:
 
 ```typescript
 project.deps.addDependency(dep, type);
 ```
 
 By default, `pdk` will automatically install dependencies in your project if they are not already installed. You can also install your dependencies manually by running `pdk install` from the root of your monorepo.
 
-## Semantic Requirements
+## Semantic requirements
 
-The first argument (dep) is a string in the form MODULE@VERSION where MODULE is the package-manager specific name of the dependency (i.e. for node projects, this is the npm module name) and VERSION is an optional semantic version requirement (e.g. @^7).
+The first argument (dep) is a string in the form MODULE@VERSION where MODULE is the package-manager specific name of the dependency (for node projects, this is the npm module name) and VERSION is an optional semantic version requirement (for example, @^7).
 
-## Dependency Types
+## Dependency types
 
 The second argument (type) defines the dependency type and is one of:
 

packages/monorepo/docs/developer_guides/monorepo/dependency_visualization.md

@@ -1,8 +1,8 @@
 # Visualize your dependency graph
 
-As your codebase grows, the number of sub-packages will likely increase and it is sometimes useful to be able to visualize your project and task dependencies. To do this, simply run `pdk graph` from the root of the monorepo which will open a browser for you.
+As your codebase grows, the number of sub-packages will likely increase and it is sometimes useful to visualize your project and task dependencies. To do this, simply run `pdk graph` from the root of the monorepo which will open a browser for you.
 
-You will now be able to visualize your project level dependencies (i.e. package a depends on package b) along with your task level (order in which tasks are performed i.e. build) dependencies.
+You can now visualize your project level dependencies (i.e. package a depends on package b) along with your task level (order in which tasks are performed i.e. build) dependencies.
 
 === "Project Level"
 

packages/monorepo/docs/developer_guides/monorepo/escape_hatches.md

@@ -1,10 +1,10 @@
 # Escape hatches
 
-It’s possible that the PDK and/or Projen doesn’t have the right high-level or low-level APIs that you need for managing your project configuration. If you think there’s an API that would be useful, first consider checking on GitHub to see if anyone else has the same problem, or consider opening an issue! But in the meantime, there are ways you can bypass projen’s regular APIs to add special configuration code.
+It is possible that the PDK and/or Projen doesn’t have the right high-level or low-level APIs that you need for managing your project configuration. If you think there’s an API that would be useful, first consider checking on GitHub to see if anyone else has the same problem, or consider opening an issue. In the meantime, there are ways you can bypass projen’s regular APIs to add a special configuration code.
 
 ## Overrides
 
-For any “object”-based files, such as JSON, YAML, TOML, or XML, you can override properties through the addOverride, addDeletionOverride, addToArray and patch methods accessible on file objects:
+For any “object”-based files, such as JSON, YAML, TOML, or XML, you can override properties through the `addOverride`, `addDeletionOverride`, `addToArray` and patch methods accessible on file objects:
 
 ```typescript
 // Get the ObjectFile
@@ -23,7 +23,7 @@ packageJson.addOverride('bundledDependencies.3', 'react');
 
 ## Removing files
 
-You can remove a file from the project through tryRemoveFile method on the Project class.
+You can remove a file from the project through `tryRemoveFile` method on the Project class.
 
 ```typescript
 new TextFile(project, "hello.txt", { lines: "original" });
@@ -34,6 +34,6 @@ new TextFile(project, "hello.txt", { lines: "better" });
 ```
 
 !!!note
-    It’s recommended that this is used carefully since removing files may be unexpected for users depending on where it’s used. For example, if you created a component named MyFancyGitIgnore and had it remove any existing .gitignore files in the project, then users may be surprised when customizations for their existing .gitignore file are nullified.
+    It is recommended that this is used carefully as removing files may be unexpected for users depending on where it is used. For example, if you created a component named MyFancyGitIgnore and had it remove any existing `.gitignore` files in the project, then users may be surprised when customizations for their existing .gitignore file are nullified.
 
 _Sourced from: https://projen.io/escape-hatches.html_

packages/monorepo/docs/developer_guides/monorepo/index.md

@@ -6,13 +6,13 @@
 
 > Simplify the management of multiple packages within a polyglot monorepo
 
-The `monorepo` submodule provides several projen project types in either Typescript, Python or Java that can configure a [NX](https://nx.dev/getting-started/intro) monorepo that can manage all of your packages. When used, these project types enable polyglot builds, declarative dependency management, build caching, dependency visualization and much, much more.
+The `monorepo` submodule provides several projen project types in either Typescript, Python or Java that can configure a [NX](https://nx.dev/getting-started/intro) monorepo to manage all your packages. When used, these project types enable polyglot builds, declarative dependency management, build caching, dependency visualization and other features.
 
-The AWS PDK itself uses the `monorepo` submodule and is a good reference for seeing how a complex, polyglot monorepo can be set up.
+The AWS PDK itself uses the `monorepo` submodule and is a good reference for seeing how to set up a complex, polyglot monorepo.
 
 ## How does it work?
 
-The construct will set up your root project to function as a Monorepo using [NX](https://nx.dev/getting-started/intro), and as such manages all of the NX configuration for you by default. Depending on the language you decide to bootstrap your project with, a projenrc file in your preferred language will be present which will allow you to add new sub-packages to your project which will be managed by NX.
+The construct will set up your root project to function as a Monorepo using [NX](https://nx.dev/getting-started/intro), and manage all of the NX configuration for you by default. Depending on the language you decide to bootstrap your project with, a `projenrc`` file in your preferred language  allows you to add new sub-packages to your project to be managed by NX.
 
 The default structure of your project will be created with the following key files as shown:
 
@@ -54,23 +54,23 @@ The default structure of your project will be created with the following key fil
     ```
 
 !!!note
-    For non-ts monorepos, yarn is still used as a package manager at the root level in order for homogenous typescript -> typescript dependencies to work. For example if you have a python monorepo with two typescript based projects that depend on each other.
+    For non-ts monorepos, yarn is still used as a package manager at the root level in order for homogenous typescript -> typescript dependencies to work. For example, when you have a python monorepo with two typescript based projects that depend on each other.
 
 ## Getting started
 
-This section describes how to get started with the `monorepo` construct. For more information, please refer to the developer guides for particular features of this construct.
+This section describes how to get started with the `monorepo` construct. For more information, refer to the developer guides for particular features of this construct.
 
 ### Create your monorepo project
 
-To get started, simply run the following command in an empty directory to create your Monorepo project:
+To get started, run the following command in an empty directory to create your Monorepo project:
 
 === "TS"
 
     ```bash
     pdk new monorepo-ts
     ```
 
-    This will bootstrap your project given the above structure and contain the _.projenrc.ts_ file containing your project definition which should contain the following:
+    This will bootstrap your project given the above structure and contain the _.projenrc.ts_ file with your project definition which should contain the following:
 
     ```ts
     import { MonorepoTsProject } from "@aws/pdk/monorepo";
@@ -88,7 +88,7 @@ To get started, simply run the following command in an empty directory to create
     pdk new monorepo-java
     ```
 
-    This will bootstrap your project given the above structure and contain the _projenrc.java_ file containing your project definition which should contain the following:
+    This will bootstrap your project given the above structure and contain the _projenrc.java_ file with your project definition which should contain the following:
 
     ```java
     import software.aws.awspdk.monorepo.MonorepoJavaProject;
@@ -110,7 +110,7 @@ To get started, simply run the following command in an empty directory to create
     pdk new monorepo-py
     ```
 
-    This will bootstrap your project given the above structure and contain the _.projenrc.py_ file containing your project definition which should contain the following:
+    This will bootstrap your project given the above structure and contain the _.projenrc.py_ file with your project definition which should contain the following:
 
     ```python
     from aws_pdk.monorepo import MonorepoPythonProject
@@ -125,10 +125,10 @@ To get started, simply run the following command in an empty directory to create
     ```
 
     !!! bug
-        `@aws/pdk/monorepo` can be removed from _dev_deps_ as this is erroneously added by Projen due to a bug in their bootstrapping process.
+        You can remove `@aws/pdk/monorepo` from _dev_deps_ as this is incorrectly added by Projen due to a bug in their bootstrapping process.
 
 !!!tip
-    You can also pass in options parameters into the `pdk new` command. For example, if you wanted to bootstrap a typescript monorepo with PNPM as the default package manager you could do: `pdk new monorepo-ts --package-manager=pnpm`. All available attributes available within the construct are eligible to be passed in as options in a _kebab-case_ format.
+    You can also pass in options parameters into the `pdk new` command. For example, if you want to bootstrap a typescript monorepo with PNPM as the default package manager you could do: `pdk new monorepo-ts --package-manager=pnpm`. You can pass all the attributes available within the construct as options in a _kebab-case_ format.
 
 ## Synthesizing your project(s)