Apply suggestions from code review

thanks, agree with all these suggestions and just layered in some minor tweaks to the suggestions.

Co-authored-by: Yusuke Tsutsumi <[email protected]>

config/hero.yaml

@@ -7,9 +7,7 @@ buttons:
 shortcuts:
   - title: Curious about the basics?
     description: |
-      AEPs are a combination of design guidance and a system to manage
-      and track that guidance. Learn more about how the AEP program works in
-      the first AEP!
+      AEPs are a collection of API design specifications, design patterns, and guidance. In addition, the AEP project includes tools to help produce AEP-compliant APIs, as well a clients (command-lines, UIs, Declarative plugins) that consume them. Learn more about how the AEP program works in the first AEP!
     button:
       href: /1
       text: Read AEP-1
@@ -21,10 +19,11 @@ shortcuts:
     button:
       href: /contributing
       text: Contribute to the project
-  - title: Want to use AEPs in your organization?
+  - title: Want to adopt AEPs in your organization?
     description: |
-      AEPs were adapted from [Google's AIP project](https://google.aip.dev/), 
-      and offer benefits and tooling that result in better designed APIs.
+      AEPs were adapted from [Google's AIP project](https://google.aip.dev/), but also extend it with
+      tooling to easily generate and validate that result in better designed APIs, as well as provide clients to 
+      consume them.
     button:
       href: /adopting
       text: Learn more

pages/general/adopting.md

@@ -2,15 +2,15 @@
 
 By adopting the guidelines from the API Enhancement Proposals, you establish a much 
 tighter and efficient possibility space. APIs that follow the 
-[AEP guidance](https://aep.dev) from the design stage are:
+[AEP guidance](https://aep.dev) from the design stage:
 
-- More consistent APIs within and across teams, reducing cognitive load for consumers
-- Argue less about API design decisions, saving time thanks to AEPs explar design patterns
+- are more consistent  within and across teams, reducing cognitive load for API consumers
+- reduce arguments  about API design decisions, thanks to the AEP specification, tools, and exemplar design patterns
 
 Having an AEP-compliant API also means benefitting from the AEP ecosystem of tooling, such as:
 
 - Linters and validators to ensure adherence to the AEP design specification [proto]()/[openapi]()
-- Command line tool that make it easier to work with APIs ([aepcli](https://github.com/aep-dev/aepcli))
+- A command line tool interface genreator that make it easier to work with APIs ([aepcli](https://github.com/aep-dev/aepcli))
 - Client-side and server-side code generators ([aepc](https://github.com/aep-dev/aepc))
 - A Terraform provider ([terraform-provider-aep](https://github.com/aep-dev/terraform-provider-aep))
 - ... and more! Please start a [discussion](https://github.com/aep-dev/aep.dev/discussions) if there is something you wish to see, validate, or prioritize.

pages/general/faq.md

@@ -10,12 +10,12 @@ However, AEPs have notable philosophical differences, including:
 
 - AEPs prioritize broadly applicable design guidance for any company, while AIPs
   prioritized design guidance specifically for Google (e.g., providing
-  backwards-compatibility with prior decisions to meet Gogole-specific needs).
+  backwards-compatibility with prior decisions to meet Google-specific needs).
 - AEPs are protocol-agonistic and consider both gRPC and HTTP+JSON as
   first-class protocols for which examples and other content are necessary.
-- AEPs focuses on a core specification that should not be forked, paired with a 
-  mechanism for optional organization-specific guidance extends the
-  specification. (Whereas AIPs encourage forking its guidance outright.)
+- AEPs focuses on a core specification that is not intended to be forked, paired with a 
+  mechanism for optional organization-specific guidance to extend the
+  specification. AIPs encourage forking its guidance outright.
 
 AEPs also have the advantage of hindsight, which makes it possible in some
 cases to provide better guidance. (One small example: