Add docs on typings in `package.json`

[blakeembrey]

From https://github.com/typings/registry/pull/138#issuecomment-187884462

[johnnyreilly]

Should I Use The typings Field In package.json?

Maybe. If you're relying on typings to provide type dependencies, I recommend that you omit the typings entry for now. If you don't use the typings.json file, add typings in package.json. This is because TypeScript 1.6+ comes with node module resolution built-in, but unless all the packages in the NPM dependency tree have their own typings entry inline you'll be breaking TypeScript users of your library. Typings has complete support for the node module resolution strategy used in TypeScript.

I think making this clearer is a good shout. Reading the above the following thoughts / questions occurred to me:

1. Does everyone know about the typings field in package.json? I suspect not and it's not that well documented either. I can find this and one line under "Improvements to module resolution" here and that's it. An brief explanation of this is probably worthwhile. It might be nice to link back to a thorough explanation if one exists somewhere too?
2. I'd get rid of the "Maybe" entirely; it doesn't help.
3. A basic rule of thumb is specified for using typings in package.json. It might be worth emphasising that a little more. Perhaps:

• If you're relying on Typings to provide type dependencies omit typings from package.json.
• If you don't use the typings.json file, add typings in package.json.

Then go on to explain the implications of each. The current example isn't very clear. Here's my brutal takedown of it:

This is because TypeScript 1.6+ comes with node module resolution built-in, [what does this mean?] but unless all the packages in the NPM dependency tree [every npm package you consume with *.d.ts files? Or something else?] have their own typings entry inline [inline?] you'll be breaking TypeScript users of your library**[breaking how exactly?]**). Typings has complete support for the node module resolution strategy used in TypeScript.

There's a lot of assumed knowledge in the explanation above which could do with being unpacked and clarified.

I hope this is helpful feedback; I mean it to be! :tulip: