Miscellaneous wording cleanup to federation docs (apollographql#2157)

* Miscellaneous wording cleanup to federation docs

* Change URL for graph router article

docs/source/_redirects

@@ -1,3 +1,4 @@
+/gateway/ /docs/federation/router/
 /other-servers/ /docs/federation/supported-subgraphs/
 /federation-spec/ /docs/federation/subgraph-spec/
 

docs/source/api/apollo-subgraph.mdx

@@ -92,7 +92,7 @@ const server = new ApolloServer({
 
 The name of a special **reference resolver** function you can define for every [entity](../entities/) in a subgraph schema's resolver map.
 
-The `__resolveReference` function enables your gateway's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see [Defining an entity](../entities/#defining-an-entity).
+The `__resolveReference` function enables your router's query planner to resolve a particular entity by whatever unique identifier your other subgraphs use to reference it. For details, see [Defining an entity](../entities/#defining-an-entity).
 
 The function takes the parameters listed below.
 

docs/source/config.json

@@ -25,10 +25,10 @@
       "3️⃣ Local composition": "/quickstart/local-composition",
       "4️⃣ Working with subgraphs": "/quickstart/local-subgraphs"
     },
-    "Implementing a Supergraph": {
+    "Building Your Supergraph": {
       "Subgraphs in Apollo Server": "/subgraphs",
       "Other subgraph libraries": "/supported-subgraphs",
-      "Graph router/gateway": "/gateway"
+      "The graph router/gateway": "/router"
     },
     "Federated Schemas": {
       "Overview": "/federated-types/overview",

docs/source/entities-advanced.mdx

@@ -116,7 +116,7 @@ The steps for this migration depend on how you perform schema composition:
 
 3. Deploy the updated Billing subgraph to your environment.
 
-    * At this point, the Billing subgraph can successfully resolve `Bill` objects, but the gateway doesn't _know_ this yet because its supergraph schema hasn't been updated.
+    * At this point, the Billing subgraph can successfully resolve `Bill` objects, but the router doesn't _know_ this yet because its supergraph schema hasn't been updated.
 
 4. In the Payments subgraph, remove the `Bill` entity and its associated resolvers (**do not deploy this change yet**):
 
@@ -140,11 +140,11 @@ The steps for this migration depend on how you perform schema composition:
 5. Compose an updated supergraph schema with your usual configuration using `rover supergraph compose`.
     * This updated supergraph schema indicates that the Billing subgraph resolves `Bill` entities, and the Payments subgraph _doesn't_.
 
-6. Assuming CI completes successfully, deploy an updated version of your _gateway_ with the new supergraph schema.
-    * When this deployment completes, the gateway begins resolving `Bill` fields in the Billing subgraph _instead of_ the Payments subgraph.
+6. Assuming CI completes successfully, deploy an updated version of your _router_ with the new supergraph schema.
+    * When this deployment completes, the router begins resolving `Bill` fields in the Billing subgraph _instead of_ the Payments subgraph.
 
 7. Deploy an updated version of your Payments subgraph without the `Bill` entity.
-    * At this point it's safe to remove this definition, because the gateway is never resolving `Bill` with the Payments subgraph.
+    * At this point it's safe to remove this definition, because the router is never resolving `Bill` with the Payments subgraph.
 
 We're done! `Bill` is now resolved in a new subgraph, and it was resolvable during each step of the migration process.
 
@@ -214,11 +214,11 @@ extend schema
 
 5. Deploy the updated Billing subgraph to your environment.
 
-    * This change is currently invisible to your gateway, which is not yet aware that the Billing subgraph defines the `Bill` entity.
+    * This change is currently invisible to your router, which is not yet aware that the Billing subgraph defines the `Bill` entity.
 
 6. Publish the updated Billing subgraph schema to Apollo.
 
-    * When the gateway fetches its new supergraph schema, it detects that it should resolve the `Bill` entity in the Billing subgraph _instead of_ in the Payments subgraph.
+    * When the router fetches its new supergraph schema, it detects that it should resolve the `Bill` entity in the Billing subgraph _instead of_ in the Payments subgraph.
 
 7. In the Payments subgraph, _remove_ the `Bill` entity and its associated resolvers:
 
@@ -241,7 +241,7 @@ extend schema
 
 8. Publish the updated Payments subgraph schema to Apollo.
 
-    * When the gateway fetches its new supergraph schema, it continues resolving the `Bill` entity in the Billing subgraph. The `@override` directive has no effect if a field is defined in only one subgraph.
+    * When the router fetches its new supergraph schema, it continues resolving the `Bill` entity in the Billing subgraph. The `@override` directive has no effect if a field is defined in only one subgraph.
 
 9. Deploy the updated Payments subgraph to your environment.
 
@@ -418,7 +418,7 @@ We can perform this migration with the following steps (additional commentary on
 
     </CodeColumns>
 
-5. Compose a new supergraph schema. Deploy a new version of your gateway that uses the updated schema.
+5. Compose a new supergraph schema. Deploy a new version of your router that uses the updated schema.
 
 6. Deploy the updated Products subgraph to your environment.
 
@@ -437,9 +437,9 @@ type Product @key(fields: "id") {
 }
 ```
 
-As shown, you use the `@requires` directive to indicate which fields (and subfields) from _other_ subgraphs are required. You also need to _define_ the required fields and apply the `@external` directive to them. This directive tells the gateway, "This subgraph knows that these fields exist, but it _can't_ resolve them itself."
+As shown, you use the `@requires` directive to indicate which fields (and subfields) from _other_ subgraphs are required. You also need to _define_ the required fields and apply the `@external` directive to them. This directive tells the router, "This subgraph knows that these fields exist, but it _can't_ resolve them itself."
 
-In the above example, if a query requests a product's `shippingEstimate`, the gateway does the following, in order:
+In the above example, if a query requests a product's `shippingEstimate`, the router does the following, in order:
 
 1. It queries the Products subgraph for the product's `size` and `weight`.
 2. It queries the Shipping subgraph for the product's `shippingEstimate`. The `size` and `weight` are included in the `Product` object passed to the resolver for `shippingEstimate`:
@@ -472,7 +472,7 @@ In this modification of the previous example, `size` and `weight` are now subfie
 
 By default, exactly one subgraph is responsible for resolving each field in your supergraph schema (with some exceptions, like entity `@key` fields). But sometimes, _multiple_ subgraphs are able to resolve a particular entity field, because all of those subgraphs have access to a particular data store. For example, an Inventory subgraph and a Products subgraph might both have access to the database that stores all product-related data.
 
-You can enable multiple subgraphs to resolve a particular entity field. **This is a completely optional optimization.** When the gateway plans a query's execution, it looks at which fields are available from each subgraph. It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields.
+You can enable multiple subgraphs to resolve a particular entity field. **This is a completely optional optimization.** When the router plans a query's execution, it looks at which fields are available from each subgraph. It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields.
 
 You achieve this with one of the following directives:
 
@@ -565,8 +565,8 @@ type Product @key(fields: "id") {
 
 Here we're using two directives in combination: `@provides` and `@external`.
 
-* The `@provides` directive tells the gateway, "This subgraph can resolve the `name` of any `Product` object returned by `InStockCount.product`."
-* The `@external` directive tells the gateway, "This subgraph _can't_ resolve the `name` of a `Product` object, _except_ wherever indicated by `@provides`."
+* The `@provides` directive tells the router, "This subgraph can resolve the `name` of any `Product` object returned by `InStockCount.product`."
+* The `@external` directive tells the router, "This subgraph _can't_ resolve the `name` of a `Product` object, _except_ wherever indicated by `@provides`."
 
 #### Rules for using `@provides`
 

docs/source/entities.mdx

@@ -55,7 +55,7 @@ type Product @key(fields: "id") {
 
 The `@key` directive defines the entity's **primary key**, which consists of one or more of the type's `fields`. In this example, the `Product` entity's primary key is its `id` field.
 
-**Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your gateway to associate field data from _different_ subgraphs with the _same_ entity instance.
+**Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your router to associate field data from _different_ subgraphs with the _same_ entity instance.
 
 > **An entity's `@key` _cannot_ include:**
 >
@@ -66,7 +66,7 @@ The `@key` directive defines the entity's **primary key**, which consists of one
 
 ### 2. Define a reference resolver
 
-The `@key` directive effectively tells the gateway, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity.
+The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity.
 
 > ⚠️ **This section describes how to create reference resolvers in Apollo Server.** If you're using another [subgraph-compatible library](./supported-subgraphs/), see its documentation for creating reference resolvers.
 
@@ -89,7 +89,7 @@ Let's break this example down:
 * You declare an entity's reference resolver in your resolver map, as a member of the entity's corresponding object.
 * A reference resolver's name is always `__resolveReference`.
 * A reference resolver's first parameter is a **representation** of the entity being resolved.
-    * An entity representation is an object that contains the entity's `@key` fields, plus its `__typename` field. These values are provided by the gateway.
+    * An entity representation is an object that contains the entity's `@key` fields, plus its `__typename` field. These values are provided by the router.
 * A reference resolver is responsible for returning all of the entity fields that this subgraph defines.
     * In this example, the hypothetical `fetchProductByID` function fetches a particular `Product`'s field data based on its `id`.
 
@@ -120,7 +120,7 @@ type Product @key(fields: "id") {
 
 </CodeColumns>
 
-When a subgraph contributes entity fields, no _other_ subgraph knows about those fields—only the gateway does thanks to the composed supergraph schema.
+When a subgraph contributes entity fields, no _other_ subgraph knows about those fields—only the router does thanks to the composed supergraph schema.
 
 By default, each subgraph must contribute _different_ fields, with the important exception of `@key` fields. Otherwise, a composition error occurs. To override this default, see [Resolving another subgraph's field](./entities-advanced/#resolving-another-subgraphs-field).
 
@@ -202,7 +202,7 @@ type Query {
 
 > Notice that the Reviews subgraph [references the `Product` entity without contributing fields](#referencing-an-entity-without-contributing-fields).
 
-The Reviews subgraph defines one entry point into our schema: `Query.latestReviews`. This means that the following query is valid against our gateway:
+The Reviews subgraph defines one entry point into our schema: `Query.latestReviews`. This means that the following query is valid against our router:
 
 ```graphql {6}
 query GetReviewsWithProducts {
@@ -218,20 +218,20 @@ query GetReviewsWithProducts {
 
 Here we have a problem: this query needs to start its execution in the Reviews subgraph (because that's where `latestReviews` is defined), but that subgraph _doesn't_ know that `Product` entities have a `price` field! Remember, the Reviews subgraph only knows about the `id` field of `Product`.
 
-Because of this, the gateway needs to fetch `price` from the Products subgraph instead. To handle this two-step process, the gateway generates a **query plan**.
+Because of this, the router needs to fetch `price` from the Products subgraph instead. To handle this two-step process, the router generates a **query plan**.
 
 ### The query plan
 
-> Query plans are automatically generated and carried out by the gateway. You don't need to write any code related to them.
+> Query plans are automatically generated and carried out by the router. You don't need to write any code related to them.
 
-A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. The gateway generates a query plan for each unique operation that it receives from clients.
+A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Your router generates a query plan for each unique operation that it receives from clients.
 
-With our example query above, the gateway knows the following:
+With our example query above, the router knows the following:
 
 * It _must_ start by querying the Reviews subgraph, because that's where `Query.latestReviews` is defined.
 * It _must_ then query the Products subgraph to fetch the `price` of each `Product` returned by the Reviews subgraph.
 
-Using this information, the gateway's query plan starts with this query to the Reviews subgraph:
+Using this information, the router's query plan starts with this query to the Reviews subgraph:
 
 ```graphql {5}
 query {
@@ -245,11 +245,11 @@ query {
 }
 ```
 
-Notice that this query omits the `Product.price` field but _adds_ the `Product.__typename` field! This is because the gateway needs **representations** of each returned `Product` entity for its _second_ query.
+Notice that this query omits the `Product.price` field but _adds_ the `Product.__typename` field! This is because the router needs **representations** of each returned `Product` entity for its _second_ query.
 
 > As described in [Define a reference resolver](#2-define-a-reference-resolver), an entity representation is an object that contains the entity's `@key` fields (`id` in this case), plus its `__typename` field.
 
-This first query returns a list of `Review` objects, each containing a `Product` representation. With these representations, the gateway can execute its second query, this time on the Products subgraph:
+This first query returns a list of `Review` objects, each containing a `Product` representation. With these representations, the router can execute its second query, this time on the Products subgraph:
 
 ```graphql
 query {
@@ -261,9 +261,9 @@ query {
 }
 ```
 
-This query uses a special entry point that's automatically added to every subgraph schema: `Query._entities`. This entry point is what provides the gateway with random access to any entity's fields.
+This query uses a special entry point that's automatically added to every subgraph schema: `Query._entities`. This entry point is what provides the router with direct access to any entity's fields.
 
-Each item in the `representations` list argument above is one of the `Product` representations that the gateway obtained from its _first_ query. Here's an example list:
+Each item in the `representations` list argument above is one of the `Product` representations that the router obtained from its _first_ query. Here's an example list:
 
 ```json
 [
@@ -279,7 +279,7 @@ Each item in the `representations` list argument above is one of the `Product` r
 ]
 ```
 
-These representations are passed individually to the `Product` [reference resolver](#2-define-a-reference-resolver) in the Products subgraph. When the reference resolver finishes returning values for each representation, the gateway receives its response:
+These representations are passed individually to the `Product` [reference resolver](#2-define-a-reference-resolver) in the Products subgraph. When the reference resolver finishes returning values for each representation, the router receives its response:
 
 ```json
 [
@@ -293,7 +293,7 @@ These representations are passed individually to the `Product` [reference resolv
 ]
 ```
 
-Nice! The gateway can merge this `price` data with the `Product` objects returned by its first query. After doing so, the gateway returns a single, combined result to the client.
+Nice! The router can merge this `price` data with the `Product` objects returned by its first query. After doing so, the router returns a single, combined result to the client.
 
 > [Learn more about query plans.](./query-plans/)
 

docs/source/federated-types/composition.mdx

@@ -35,7 +35,7 @@ To learn how to install Rover and use this command, see the [quickstart](../quic
 
 ### Automatically with managed federation
 
-With [managed federation](../managed-federation/overview/), Apollo performs composition automatically whenever one of your subgraphs updates its registered schema. This enables your running graph router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available:
+With [managed federation](../managed-federation/overview/), Apollo performs composition automatically whenever one of your subgraphs updates its published schema. This enables your running graph router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available:
 
 ```mermaid
 graph LR;
@@ -67,13 +67,13 @@ For example, take a look at these two subgraph schemas:
 <CodeColumns>
 
 ```graphql {2} title="Subgraph A"
-type Event {
+type Event @shareable {
   timestamp: String!
 }
 ```
 
 ```graphql {2} title="Subgraph B"
-type Event {
+type Event @shareable {
   timestamp: Int!
 }
 ```

docs/source/federated-types/federated-directives.mdx

@@ -224,7 +224,7 @@ See also [Value types in Apollo Federation](./sharing-types/) and [Resolving ano
 directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 ```
 
-Indicates that a definition in the subgraph schema should be _omitted_ from the gateway's [API schema](./overview/#api-schema), _even if that definition is also present in other subgraphs_. This means that the field is not exposed to clients at all.
+Indicates that a definition in the subgraph schema should be _omitted_ from the router's [API schema](./overview/#api-schema), _even if that definition is also present in other subgraphs_. This means that the field is not exposed to clients at all.
 
 Common use cases for `@inaccessible` include:
 
@@ -497,7 +497,7 @@ Examples:
 directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 ```
 
-Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. Apollo Studio's enterprise [contracts feature](/studio/contracts/) uses `@tag` to define inclusion and exclusion filters.
+Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. Apollo Studio's enterprise [contracts feature](/studio/contracts/) uses `@tag` with its inclusion and exclusion filters.
 
 > ⚠️ Unlike with most directives, composition _preserves_ uses of this directive in the generated supergraph schema. To preserve uses of _other_ directives, see [`@composeDirective`](#composedirective).
 >