Stubbing out the aep tooling list

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 we use 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 for your organization?
+  - title: Want to adopt AEPs in your organization?
     description: |
-      AEPs are designed to be useful outside of Google. Take a look at how you
-      might choose which AEPs are best suited to your API design needs.
+      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

@@ -1,11 +1,16 @@
 # Adopting AEPs for your company
 
-Currently, we encourage adoption of AEPs via having your APIs adhere to the
-guidance served at https://aep.dev.
+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:
 
-In the future, we plan to introduce a broader ecosystem of tooling including:
+- 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
 
-- A forkable repository which allows for internal mirrors and
-  organization-specific guidance.
-- Client-side and server-side code generators.
-- Validators to ensure adherence to the specification.
+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]()
+- 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

@@ -1,22 +1,22 @@
 # Frequently Asked Questions
 
-## What is the difference between aep.dev and google.aip.dev?
+## What are the differences between AEPs and AIPs?
 
-As aep.dev is derived from [google.aip.dev](https://google.aip.dev), a lot of
-content will be familiar.
+If you are familiar with Google's API Improvement Proposals 
+[google.aip.dev](https://google.aip.dev), then much of the 
+[API Enhancement Proposals](https://aep.dev) content will be familiar.
 
-However, aep.dev has significant philosophical differences:
+However, AEPs have notable philosophical differences, including:
 
-- aep.dev prioritizes broadly applicable design guidance, while google.aip.dev
-  prioritizes design guidance this best for Google, such as guidance that is
-  backwards-compatible with existing decisions at the company.
-- aep.dev is protocol-agonistic, and considers gRPC and HTTP + JSON as
-  first-class protocols for which examples and other content will be authored.
-- google.aip.dev encourages forking the guidance, while aep.dev focuses on a
-  set of core specification that should not be forked, paired with a method to
-  add organization-specific guidance that does not contradict the
-  specification.
+- 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 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 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.
 
-aep.dev also has the advantage of hindsight, which makes it possible in some
-cases to provide better guidance than google.aip.dev. (One small example:
+AEPs also have the advantage of hindsight, which makes it possible in some
+cases to provide better guidance. (One small example:
 renaming `page_size` to `max_page_size` for requests to paginated API methods.)