Update READMEs

README.md

@@ -9,10 +9,31 @@ A monorepo for formerly disparate DefinitelyTyped-related tools:
 - [publisher](packages/publisher): the rest of [microsoft/types-publisher](https://github.com/microsoft/types-publisher)
 - [utils](packages/utils): shared utilities, mostly extracted from [microsoft/types-publisher](https://github.com/microsoft/types-publisher)
 
-## Local development
+## Disclaimer
+
+These tools are not intended for public consumption, so we may break the API whenever convenient for us.
+
+## Contributing
 
 This is a monorepo managed with [lerna](https://github.com/lerna/lerna). After cloning, run `npm install`. `lerna bootstrap` will be run automatically to install dependencies in each of the individual packages.
 
+### Adding/updating dependencies
+
+Rather than using `npm install` in individual packages, use [`lerna add`](https://github.com/lerna/lerna/tree/master/commands/add#readme) from the root. Examples:
+
+```sh
+# To add `glob` to definitions-parser:
+lerna add glob packages/definitions-parser
+
+# To add testdouble as a devDependency to publisher:
+lerna add --dev testdouble packages/publisher
+
+# To add typescript to all packages:
+lerna add typescript
+```
+
+The exception to this rule is devDependencies that are shared between all packages: those can added to the root package.json with `npm` directly.
+
 ### Testing
 
 All packages use [jest](https://github.com/facebook/jest), with a single configuration set up to be run from the monorepo root. `npm test` is an alias for `jest`, so you can run tests with any of [jest’s CLI options](https://jestjs.io/docs/en/cli). For example, to run tests for a single package:
@@ -20,3 +41,7 @@ All packages use [jest](https://github.com/facebook/jest), with a single configu
 ```sh
 npm test -- packages/utils
 ```
+
+### Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

packages/definitions-parser/README.md

@@ -1,11 +1,7 @@
-# `@definitelytyped/definitions-parser`
+# definitions-parser
 
-> TODO: description
+Extracted from [types-publisher](https://github.com/microsoft/types-publisher). Parts of the [publisher](../publisher) README describe functionality of this package, but since this was previously internal API, docs are sparse. Essentially, this package is responsible for
 
-## Usage
-
-```
-const definitionsParser = require('@definitelytyped/definitions-parser');
-
-// TODO: DEMONSTRATE API
-```
+1. Downloading a copy of the DefinitelyTyped repository from GitHub (optional—a local copy can be used instead).
+2. Reading all definitions from that repository, doing some analysis, and caching that data in the `data` directory.
+3. Providing a programmatic API wrapper around that data.

packages/utils/README.md

@@ -1,11 +1,3 @@
-# `@definitelytyped/utils`
+# @definitelytyped/utils
 
-> TODO: description
-
-## Usage
-
-```
-const utils = require('@definitelytyped/utils');
-
-// TODO: DEMONSTRATE API
-```
+Common utilities shared between DefinitelyTyped tools. Mostly extracted from [types-publisher](https://github.com/microsoft/types-publisher).