Various tidying in the federation docset

docs/source/config.json

@@ -25,7 +25,7 @@
  "3️⃣ Local schema composition": "/quickstart/local-composition",
  "4️⃣ Working with subgraphs": "/quickstart/local-subgraphs"
  },
- "Implementing": {
+ "Implementing a Supergraph": {
  "Subgraphs": "/subgraphs",
  "The gateway": "/gateway"
  },

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

@@ -22,7 +22,7 @@ Types like this are called **value types**. This article describes how to share
 
 ## Sharing object types
 
-By default in [Federation 2 subgraphs](../federation-2/moving-to-federation-2/#phase-2-modify-subgraph-schemas), a single object field _can't_ be defined or resolved by more than one subgraph schema.
+By default in [Federation 2 subgraphs](../federation-2/moving-to-federation-2/#step-3-update-individual-subgraphs), a single object field _can't_ be defined or resolved by more than one subgraph schema.
 
 Consider the following `Position` example:
 

docs/source/federation-2/backward-compatibility.mdx

@@ -5,14 +5,15 @@ description: FAQ
 
 ## Do I need to modify my subgraph schemas to use Federation 2?
 
-**Eventually.** The process of [moving to Federation 2](./moving-to-federation-2/) has two phases:
+**Eventually.** The process of [moving to Federation 2](./moving-to-federation-2/) has three steps:
 
-1. Use Federation 2 composition with your Federation 1 subgraph schemas.
-2. Convert your Federation 1 subgraph schemas to true Federation 2 subgraph schemas.
+1. Update your gateway to support Federation 2.
+2. Begin composing your supergraph schema with Federation 2 composition logic.
+3. Update your individual subgraphs to use Federation 2 features and directives.
 
-Phase 1 usually requires _no_ changes to your subgraph schemas. Schemas that _do_ require changes are schemas that _should_ cause certain composition errors that Federation 1 fails to detect ([see below.](#breaking-changes)).
+Steps 1 and 2 usually require _no_ changes to your subgraph schemas. Schemas that _do_ require changes are schemas that _should_ cause certain composition errors that Federation 1 fails to detect ([see below.](#breaking-changes)).
 
-Phase 2 _does_ require some changes to your subgraph schemas, described [here](./moving-to-federation-2/#phase-2-modify-subgraph-schemas).
+Step 3 _does_ require some changes to your subgraph schemas, described [here](./moving-to-federation-2/#step-3-update-individual-subgraphs).
 
 
 ### Breaking changes

docs/source/federation-2/moving-to-federation-2.mdx

@@ -51,11 +51,16 @@ Follow the instructions below to configure whichever composition method(s) you c
 
 If you're using [managed federation](../managed-federation/overview/), you move individual variants of your graph to Federation 2 in the Apollo Studio UI.
 
-Go to your graph's Settings page and open the Variants section:
+Open the Settings page for the variant you want to move to Federation 2, then select the **This Variant** tab:
 
-<img class="screenshot" alt="Edit supported directives in Studio" src="../images/edit-build-configuration.jpg" width="600"/>
+<img
+ class="screenshot"
+ alt="Edit variant settings in Studio"
+ src="../images/variant-settings.jpg"
+ width="600"
+/>
 
-Click **Edit Build Configuration** for the variant you want to move to Federation 2. The following dialog appears:
+Click **Edit Configuration**. The following dialog appears:
 
 <img class="screenshot" alt="Edit supported directives in Studio" src="../images/set-federation-version.jpg" width="600"/>
 

docs/source/federation-2/new-in-federation-2.mdx

@@ -12,11 +12,12 @@ If you're just getting started with Federation, check out the [Quickstart](../qu
 
 Before covering what's new, here's what _isn't_ changing in Federation 2:
 
-* Most importantly, **Federation 2 is backward compatible with most Federation 1 graphs.** You can probably move your existing graph to use Federation 2 composition without making any changes.
+* Most importantly, **Federation 2 is backward compatible with most Federation 1 supergraphs.** You can probably move your existing supergraph to use Federation 2 composition without making any changes.
  * Graphs that _do_ require changes are graphs that _should_ cause composition errors, but Federation 1 fails to detect them. [Learn more.](./backward-compatibility/#do-i-need-to-modify-my-subgraph-schemas-to-use-federation-2)
  * To take full advantage of Federation 2 features, you do need to make some changes to your subgraph schemas, but you can make these changes incrementally at your convenience. See [Moving to Apollo Federation 2](./moving-to-federation-2/).
 
-* Subgraph servers have _no_ additional requirements. Any [subgraph-compatible library](../other-servers/) is automatically compatible with Federation 2.
+* Subgraph servers have no additional requirements. Any [subgraph-compatible library](../other-servers/) is automatically compatible with Federation 2.
+ * Many subgraph-compatible libraries do not yet automatically define certain directives that are new in Federation 2, such as `@shareable`. You can [define these directives manually](./moving-to-federation-2/#add-directive-definitions-if-needed) to use them in your subgraph schemas.
 
 ## More flexible composition
 

docs/source/gateway.mdx

@@ -2,11 +2,11 @@
 title: Implementing the gateway
 ---
 
-> 📣 **The Apollo Router** is a new high-performance graph router written in Rust that is currently in alpha. You can try out the Apollo Router in place of the Apollo Gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/)
+> 📣 **The Apollo Router** is a new high-performance graph router written in Rust that is currently in preview. You can try out the Apollo Router in place of the Apollo Gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/)
 
-After you set up at least one federation-ready [subgraph](./subgraphs/), you can configure a **gateway** to sit in front of your subgraphs. The gateway executes incoming operations across those subgraphs.
+After you set up at least one federation-ready [subgraph](./subgraphs/), you can configure a **gateway** to sit in front of your subgraphs. The gateway serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs.
 
-The [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) package extends Apollo Server's functionality, enabling it to act as a gateway for an Apollo Federation architecture.
+The [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) package extends Apollo Server's functionality, enabling it to act as the gateway for a supergraph.
 
 > We recommend against running your gateway in a serverless environment (such as AWS Lambda), because schema composition increases Apollo Server's startup time. If you _do_ run your gateway in a serverless environment, set your function's timeout to at least 10 seconds to prevent unexpected errors.
 
@@ -15,20 +15,20 @@ The [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) package e
 First, let's install the necessary packages:
 
 ```shell
-npm install @apollo/gateway@latest-2 apollo-server graphql
+npm install @apollo/gateway apollo-server graphql
 ```
 
 The `@apollo/gateway` package includes the [`ApolloGateway` class](./api/apollo-gateway/). To configure Apollo Server to act as a gateway, you pass an instance of `ApolloGateway` to the `ApolloServer` constructor, like so:
 
-```js {8-12,14-17} title="index.js"
+```js {7-11,13-16} title="index.js"
 const { ApolloServer, gql } = require('apollo-server');
 const { ApolloGateway } = require('@apollo/gateway');
 const { readFileSync } = require('fs');
 
 const supergraphSdl = readFileSync('./supergraph.graphql').toString();
 
 // Initialize an ApolloGateway instance and pass it
-// the supergraph schema
+// the supergraph schema as a string
 const gateway = new ApolloGateway({
  supergraphSdl,
 });
@@ -65,7 +65,7 @@ const { readFile } = require('fs/promises');
 let supergraphUpdate;
 const gateway = new ApolloGateway({
  async supergraphSdl({ update }) {
- // `update` is a function which we'll save for later use
+ // `update` is a function that we'll save for later use
  supergraphUpdate = update;
  return {
  supergraphSdl: await readFile('./supergraph.graphql', 'utf-8'),
@@ -89,7 +89,7 @@ Note that `supergraphSdl` is now an `async` function. This function is called ex
 - It receives the `update` function, which we use to update the supergraph schema.
 - It returns the initial supergraph schema, which the gateway uses at startup.
 
-With the `update` function, we can now programatically update the supergraph. Polling, webhooks, and file watchers are all good examples of ways we can go about updating the supergraph.
+With the `update` function, we can now programatically update the supergraph schema. Polling, webhooks, and file watchers are all examples of ways we can go about doing this.
 
 The code below demonstrates a more complete example using a file watcher. In this example, assume that we're updating the `supergraphSdl.graphql` file with the Rover CLI.
 
@@ -226,7 +226,7 @@ After adding the `userId` to the shared `context` object, the gateway can then a
 
 <ExpansionPanel title="Expand example">
 
-```javascript {6-12,17-19,24-31}
+```javascript {7-13,17-19,25-32}
 const { ApolloServer } = require('apollo-server');
 const { ApolloGateway, RemoteGraphQLDataSource } = require('@apollo/gateway');
 const { readFileSync } = require('fs');

docs/source/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction to Apollo Federation
-description: Combine GraphQL APIs into a unified graph
+description: Combine GraphQL APIs into a unified supergraph
 ---
 
 import FederationArchitecture from '../shared/diagrams/federation-architecture.mdx';
@@ -12,7 +12,7 @@ import FederationArchitecture from '../shared/diagrams/federation-architecture.m
 >
 > Docs for Federation 1 are [available here](/federation/v1/).
 
-**Apollo Federation** is a powerful open-source architecture that helps you create a **unified graph** that combines multiple GraphQL APIs:
+**Apollo Federation** is a powerful open-source architecture that helps you create a **unified supergraph** that combines multiple GraphQL APIs:
 
 ```mermaid
 graph BT;
@@ -25,9 +25,9 @@ graph BT;
  end;
 ```
 
-With federation, you can responsibly share ownership of your graph across any number of teams. And even if you currently only have _one_ GraphQL API, Apollo Federation is essential for scaling that API as you grow your features, user base, and organization.
+With federation, you can responsibly share ownership of your supergraph across any number of teams. And even if you currently only have _one_ GraphQL API, Apollo Federation is essential for scaling that API as you grow your features, user base, and organization.
 
-Federation also supports a free managed mode with Apollo Studio, which helps you modify and grow your graph without any downtime.
+Federation also supports a free managed mode with Apollo Studio, which helps you modify and grow your supergraph without any downtime.
 
 <div>
  <ButtonLink
@@ -160,7 +160,7 @@ graph TB;
 
 But with an architecture like this, a client might need to communicate with _multiple_ APIs to fetch all of the data it needs. This diminishes a powerful advantage of GraphQL over REST.
 
-Instead, your organization should expose a [unified graph](https://principledgraphql.com/integrity) that lets clients fetch _all_ of the data that they need from a single endpoint:
+Instead, your organization should expose a [unified supergraph](https://principledgraphql.com/integrity) that lets clients fetch _all_ of the data that they need from a single endpoint:
 
 <p style="margin-bottom: 0">✅</p>
 
@@ -177,7 +177,7 @@ graph BT;
  class clients secondary;
 ```
 
-By unifying your graph with Apollo Federation, teams can continue to own and develop their subgraphs independently, and clients can fetch data from _all_ of those subgraphs with a single query.
+By unifying your supergraph with Apollo Federation, teams can continue to own and develop their subgraphs independently, and clients can fetch data from _all_ of those subgraphs with a single query.
 
 ### Break up monolithic code
 
@@ -197,7 +197,7 @@ flowchart TB;
  class teamA,teamB,teamC,teamD,teamE tertiary;
 ```
 
-By federating your graph, you can reduce performance _and_ productivity bottlenecks simultaneously. Each team can maintain their own subgraph(s) independently, and your graph's gateway serves primarily to _route_ incoming operations, not to resolve each of them completely.
+With a supergraph, you can reduce performance _and_ productivity bottlenecks simultaneously. Each team can maintain their own subgraph(s) independently, and your supergraph's gateway serves primarily to _route_ incoming operations, not to resolve each of them completely.
 
 <p style="margin-bottom: 0">✅</p>
 
@@ -368,7 +368,7 @@ graph LR;
  class uplink secondary;
 ```
 
-This mode helps multiple teams working on a graph to coordinate when and how to change individual subgraphs. It's recommended for all federated graphs. For more information, read [Managed federation overview](./managed-federation/overview/).
+This mode helps multiple teams working on a supergraph to coordinate when and how to change individual subgraphs. It's recommended for all supergraphs. For more information, read [Managed federation overview](./managed-federation/overview/).
 
 ---
 

docs/source/subgraphs.mdx

@@ -4,7 +4,9 @@ title: Implementing subgraphs
 
 import FederationArchitecture from '../shared/diagrams/federation-architecture.mdx';
 
-This article describes how to create a **subgraph** for a federated graph using Apollo Server.
+This article demonstrates how to create a **subgraph** for a federated supergraph using Node.js and Apollo Server.
+
+> To create a subgraph using a different language and/or framework, see the list of [subgraph-compatible libraries](./other-servers/). Note that not all libraries provide full support for Federation features.
 
 ## Defining a subgraph
 
@@ -83,13 +85,13 @@ extend schema
 `;
 ```
 
-This definition designates a schema as a "true" Federation 2 schema. Without it, Federation 2 composition assumes a subgraph is using Federation 1, and it sets certain defaults for backward compatibility.
+This definition enables the schema to use Federation 2 features. Without it, Federation 2 composition assumes a subgraph is using Federation 1, and it sets certain defaults for backward compatibility.
 
 > As you begin using more [federation-specific directives](./federated-types/federated-directives) beyond `@key` and `@shareable`, you'll need to add those directives to the `import` array shown above.
 
 ### 3. Define an entity
 
-> Entities aren't _required_ in a subgraph, but they're a core building block of a federated graph, so it's good to get some practice defining them.
+> Entities aren't _required_ in a subgraph, but they're a core building block of a federated supergraph, so it's good to get some practice defining them.
 
 As part of our federated architecture, we want _other_ subgraphs to be able to contribute fields to the `User` type. To enable this, we add the `@key` directive to the `User` type's definition to designate it as an [entity](./entities/):