chore: minor grammar on README (#93)

README.md

@@ -1,19 +1,34 @@
 # common-schemas
 
+Decentraland data structure interfaces and validators for TypeScript-based projects.
+
+Install it with:
 ```bash
 npm i @dcl/schemas
 ```
 
-### Design considerations
+## Design Guidelines
+
+- Prevent type problems across projects
+- Fail as early as possible, aim for compile-time
+- Preserve user optionality through runtime helpers
+- Prefer no-cost implementations and allow no-dependency import
+- Code is written once, read hundreds of times
 
-- The main entrypoint of the library export types only (and the helper functions to prevent lockin)
+Implementation decisions:
+
+- The main entrypoint should only export types
 - Every type is also a namespace
 - Type names are PascalCase
 - Validators and schemas are camelCase
 
-## Generating types, validators and schemas
+### Collaborator's Guide
+
+#### Generating types, validators and schemas
 
-We will export types that also act as values. We do that using the "namespaces" of typescript. That is, every type is also a JS object, including two properties: `schema` and `validate`. It can also be a const, but a namespace _sounds_ better.
+This library export types that also act as values. This is achieved through TypeScript's [`namespaces`](https://www.typescriptlang.org/docs/handbook/namespaces.html). This means that every type imported from this library can also be used as a JS object. These types will include two properties named `schema` and `validate`. `namespaces` in typescript can be considered "`cost` imports".
+
+#### Example Type Definition
 
 ```ts
 // Declare type
@@ -36,41 +51,35 @@ export namespace MyType {
 }
 ```
 
-In that sense, MyType can be both used as type `const a: MyType` and as object `MyType.validate(a)`.
+MyType can now be both used as type `const a: MyType` or as an object `MyType.validate(a)`.
 
-Beware that `validate` has type `ValidateFunction<T>` which `ajv` creates automatically. When writing new
-validations always try to implement it as an ajv validation, even if custom code is needed. See [here](https://ajv.js.org/keywords.html#define-keyword-with-code-generation-function).
+Beware that `validate` has type `ValidateFunction<T>` which `ajv` creates automatically. When writing new validations always try to implement it as an ajv validation, even if custom code is needed. See [here](https://ajv.js.org/keywords.html#define-keyword-with-code-generation-function).
 
-In particular, don't fall in the trap of doing this:
+Particularly, beware of using the library like this, because reports by the `validator.validate` function are lost and never returned to the caller.
 
 ```ts
 const validator = generateValidator<MyType>(schema);
 export const validate = (mt: MyType) =>
   validator.validate(mt) && otherValidations(mt);
 ```
 
-By doing this, all the errors reported by the `validator.validate` function are lost and never returned
-to the caller.
-
-## Type ownership
+#### Code ownership
 
 Please add types and schemas of your domain into the `src/<team>` folder, also add your team to the [CODEOWNERS](.github/CODEOWNERS) repository to make sure nobody accidentally changes it without your team noticing it.
 
-## Informing changes
-
-Please notify about changes to the schemas to the teams by adding the whole team (i.e. `@decentraland/dapps`) as reviewers of the pull requests.
+#### Informing changes
 
-It is recommended that if you are a stakeholder of the interoperable parts of Decentraland, you are subscribed to this repository (wathing it in the button up right).
+Please notify about changes to the schemas to relevant teams by adding the whole team (i.e. `@decentraland/dapps`) as reviewers of the pull requests.
 
-## Making changes
+It is recommended to subscribe to this repository (using the `Watch` function) if you use any internal part of the Decentraland ecosystem.
 
-To make sure everybody is aware of changes in types, we have a process of api-extraction using https://api-extractor.com. It creates [a report file](report/schemas.api.md) that should be reviewed upon every change and committed as part of the PR.
+#### Making changes
 
-To generate the file with your changes run `npm run refresh-api`.
+To make sure the relevant persons and groups are aware of changes in these types, there's an api-extraction process executed with https://api-extractor.com that creates [a report file](report/schemas.api.md) for review between commits. It gets included as part of PRs for easier read.
 
-In the CI, `npm run check-api` is executed to verify the generated file matches the exported types.
+To generate the file before submitting a PR, run `npm run refresh-api`. This is executed by the CI by runnig `npm run check-api`. It also verifies that the generated file matches the exported types.
 
-## Versions and publishing
+## Versioning and Publishing
 
 Versions are handled manually using Github releases and semver.