docs: add top level introduction #33
Conversation
README.md
Outdated
| A collection of packages for defining and using type-checked apis with TypeScript. | ||
|
|
||
| TypeScript is a very powerful type system layered on top of JavaScript, but one drawback | ||
| it has is that this extra type information is not available at runtime. |
There was a problem hiding this comment.
Is it worth talking about how this constraint is not expected to change?
Non-goals
...
Add or rely on run-time type information in programs, or emit different code based on the results of the type system.
https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals#non-goals
README.md
Outdated
| TypeScript is a very powerful type system layered on top of JavaScript, but one drawback | ||
| it has is that this extra type information is not available at runtime. | ||
| [io-ts](https://github.com/gcanti/io-ts) fills in this functionality gap. | ||
| `io-ts-http`(packages/io-ts-http/README.md) builds on top of `io-ts` to make it possible |
There was a problem hiding this comment.
| `io-ts-http`(packages/io-ts-http/README.md) builds on top of `io-ts` to make it possible | |
| [`io-ts-http`](packages/io-ts-http/README.md) builds on top of `io-ts` to make it possible |
Seems helpful to provide a hyperlink here
There was a problem hiding this comment.
I dig it!
One general principle I think we can improve on is "use fewer words". That was my big take-away from working with Gwen to improve my technical writing.
For example, instead of
TypeScript is a very powerful type system layered on top of JavaScript, but one drawback it has is that this extra type information is not available at runtime
we could write
TypeScript is a very powerful type system layered on top of JavaScript, but lacks type information available at runtime
replacing 8 words with 1!
I feel we could even improve the first part of this sentence (before the comma), but iteration is the name of the game.
Thanks for putting this documentation out! 🚀
bitgopatmcl
force-pushed
the
top-level-introduction
branch
from
6215189 to
156171e
Compare
|
🎉 This PR is included in version 1.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 0.2.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 0.1.1-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 0.2.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
2 participants
No description provided.