docs feedback

README.md

@@ -13,7 +13,7 @@ polycons can be used with any CDK framework, including [AWS CDK], [cdktf], and [
 Polycons can be used just like ordinary CDK constructs:
 
 ```ts
-import { Dog } from "my-polycons";
+import { Dog } from "@acme/shared-polycons";
 import { Construct } from "constructs";
 
 class Pets extends Construct {
@@ -30,12 +30,12 @@ This construct contains a `Dog` from a library of polycons.
 The dog could have any implementation -- a `Labrador` implementation, a `Terrier` implementation, and so on.
 
 To use it in an application, you need to register a factory that specifies how to turn polycons into concrete constructs.
-In the example below, a `PetFactory` is registered to the application, ensuring that each `Dog` defined in the construct tree will be resolved into a `Labrador` under the hood.
+In the example below, a `PetFactory` is registered to the application, ensuring that each `Dog` defined in the construct tree will be resolved into a `Labrador`.
 
 ```ts
 import { App } from "<cdk-framework>";
-import { PetFactory } from "my-polycons";
-import { Polycons } from "@monadahq/polycons";
+import { PetFactory } from "@acme/shared-polycons";
+import { Polycons } from "polycons";
 
 const app = new App();
 Polycons.register(app, new PetFactory());

docs/index.md

@@ -2,11 +2,11 @@
 
 ## Polycon factories
 
-To create a polycon factory, create a class with a `resolve` method.
-This method takes a `type` and the polycon's constructor parameters, and should return a concrete construct. For example:
+A polycon factory is an object that implements the `IPolyconFactory` interface, which has a single `resolve()` method.
+This method takes a `type` and the construct arguments, and should return a concrete construct. For example:
 
 ```ts
-import { DOG_ID, CAT_ID, Labrador, Kitten } from "my-polycons";
+import { DOG_ID, CAT_ID, Labrador, Kitten } from "@acme/shared-polycons";
 
 class PetFactory implements IPolyconFactory {
   public resolve(
@@ -27,9 +27,9 @@ class PetFactory implements IPolyconFactory {
 }
 ```
 
-By customizing the `resolve` method, it's possible to change construct IDs, override properties, or even make factories out of other factories.
+By customizing the `resolve()` method, it's possible to change construct IDs, override properties, or even make factories out of other factories.
 
-## Polycons
+## Authoring polycons
 
 You can define a polycon by creating a class that returns a new Polycon instance in the constructor. Each polycon must be associated with a unique identifier.