docs: Stubbing out the aep tooling list (#238)

Including a better description of available aep tooling and a better overview, to help inform our users about the project.

----

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

Author: earth2marsh

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,10 @@ 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 enhanced with improved
+      guidance for APIs, tooling to generate and validate them, and clients to interact with them. The result is better designed and consumable APIs.
     button:
       href: /adopting
       text: Learn more

pages/general/adopting.md

@@ -1,11 +1,23 @@
 # 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](https://github.com/aep-dev/api-linter)/[openapi](https://github.com/aep-dev/aep-openapi-linter))
+- A dynamic command line interface generator 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))
+- ... 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:
-renaming `page_size` to `max_page_size` for requests to paginated API methods.)
+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.)