diff --git a/federation-js/README.md b/federation-js/README.md
index 06e7455cd..240602a95 100644
--- a/federation-js/README.md
+++ b/federation-js/README.md
@@ -1 +1,40 @@
 # `Apollo Federation Utilities`
+
+This package provides utilities for creating GraphQL microservices, which can be combined into a single endpoint through tools like [Apollo Gateway](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-gateway).
+
+For complete documentation, see the [Apollo Federation API reference](https://www.apollographql.com/docs/apollo-server/api/apollo-federation/).
+
+## Usage
+
+```js
+const { ApolloServer, gql } = require("apollo-server");
+const { buildFederatedSchema } = require("@apollo/federation");
+
+const typeDefs = gql`
+  type Query {
+    me: User
+  }
+
+  type User @key(fields: "id") {
+    id: ID!
+    username: String
+  }
+`;
+
+const resolvers = {
+  Query: {
+    me() {
+      return { id: "1", username: "@ava" }
+    }
+  },
+  User: {
+    __resolveReference(user, { fetchUserById }){
+      return fetchUserById(user.id)
+    }
+  }
+};
+
+const server = new ApolloServer({
+  schema: buildFederatedSchema([{ typeDefs, resolvers }])
+});
+```
diff --git a/gateway-js/README.md b/gateway-js/README.md
index a61f8b646..dc075ed07 100644
--- a/gateway-js/README.md
+++ b/gateway-js/README.md
@@ -1 +1,31 @@
 # Apollo Gateway
+
+This package provides utilities for combining multiple GraphQL microservices into a single GraphQL endpoint.
+
+Each microservice should implement the [federation schema specification](https://www.apollographql.com/docs/apollo-server/federation/federation-spec/). This can be done either through [Apollo Federation](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-federation) or a variety of other open source products.
+
+For complete documentation, see the [Apollo Gateway API reference](https://www.apollographql.com/docs/apollo-server/api/apollo-gateway/).
+
+## Usage
+
+```js
+const { ApolloServer } = require("apollo-server");
+const { ApolloGateway } = require("@apollo/gateway");
+
+const gateway = new ApolloGateway({
+  serviceList: [
+    { name: "accounts", url: "http://localhost:4001/graphql" },
+    // List of federation-capable GraphQL endpoints...
+  ]
+});
+
+(async () => {
+  const { schema, executor } = await gateway.load();
+
+  const server = new ApolloServer({ schema, executor });
+
+  server.listen().then(({ url }) => {
+    console.log(`🚀 Server ready at ${url}`);
+  });
+})();
+```