Title: How to capture FAQ's, Gotcha's, and other useful TypeScript details. · Issue #58 · microsoft/TypeScript-Website · GitHub
Open Graph Title: How to capture FAQ's, Gotcha's, and other useful TypeScript details. · Issue #58 · microsoft/TypeScript-Website
X Title: How to capture FAQ's, Gotcha's, and other useful TypeScript details. · Issue #58 · microsoft/TypeScript-Website
Description: Redirecting from the Roadmap issue. I think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could include FAQ's that arise from particular prop...
Open Graph Description: Redirecting from the Roadmap issue. I think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could inclu...
X Description: Redirecting from the Roadmap issue. I think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could inclu...
Opengraph URL: https://github.com/microsoft/TypeScript-Website/issues/58
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"How to capture FAQ's, Gotcha's, and other useful TypeScript details.","articleBody":"Redirecting from the Roadmap issue.\r\n\r\nI think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could include FAQ's that arise from particular properties of TypeScript, slightly more detail on certain type relationships, or some of the heuristics TypeScript uses to skip expensive checks.\r\n\r\nIn general I think this information is hard to find. Most blogs, release notes, and the handbook do not have this information. _This is not a criticism_---I think it's right that these sources are approachable. My question here is: where does this information belong, if anywhere?\r\n\r\nThere is an FAQ on the repo that includes many of the gotcha's I'm thinking of, yet they still get asked on the tracker. Maybe the reality is that most people wont read this information anyway, so this is a pointless task. I think that the GitHub wiki is hard to find and hard to digest, so I'm going to assume\u003csup>*hope\u003c/sup> that we can improve the situation here.\r\n\r\nI have very little experience interacting with developers trying to become competent and master a language, so I feel rather naïve in this regard. I doubt this problem can just be solved by writing a load of content. I'll try and go through a few examples of situations that I think could be improved, though I don't necessary have a strong recommendation of how to improve them (not helpful, I know).\r\n\r\n## FAQ or Gotcha: Strict function types and methods.\r\n\r\nI've seen this question come up a few times, or rather, people posting issues without realising there is such a behaviour: I'm referring to methods always being bivariant. The only places I know where these are documented are in the strict function types PR [here](https://github.com/microsoft/TypeScript/pull/18654), and the release notes for that version of TypeScript [here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html\r\n). AFAIK this isn't document in the handbook or FAQ.\r\n\r\nMy general comment here is that feature PR's often contain a lot of great information in them which is then usually translated to the corresponding release notes, but neither of these should be long-term replacements for specifications of behaviour. PR's can be hard to find and release notes contain lots of unrelated changes. I think there should be a consistent route to transition key PR details into the handbook, web examples, or some other resource. Could there ever be a call for documentation associated with a merged feature PR which is shepherded by someone in the team?\r\n\r\n## Interesting TypeScript details lost in the tracker.\r\n\r\nThere are a lot of interesting comments, examples, and discussion in the tracker, but unfortunately that is where it stays. I cannot assert that distilling this information and adding it to the website would have a tangible impact, but to me it feels like users shouldn't have to search the issue tracker to find information that describes the language. If the tracker is presented as somewhere not to ask questions about the language, I think it's reasonable to expect that users shouldn't have to find their answers there. Some examples:\r\n\r\n#### Why is `keyof never` should be `string | number | symbol`?\r\n\r\n[Here ](https://github.com/microsoft/TypeScript/issues/33025#issuecomment-524053918) is a comment by @weswigham that really nicely describes a particular design choice that I think would provide insight to anyone that reads it. This shouldn't be hidden away in a closed issue, but perhaps associated with some longer exposition of `keyof`.\r\n\r\n#### Behaviour of writing to an indexed access type.\r\n\r\nThere was a PR that improved indexed access types but was a breaking change. The change is motivated by some non-trivial reasoning about generics and variance but the description in the release notes was abit short: [link](https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/). If you follow many of the related issues such as [this](https://github.com/microsoft/TypeScript/issues/31672) you'll find lots of interesting discussion and examples. It would be great if some of this content made it into the website: maybe have a playground instance for indexed access types that takes some of these correct and incorrect examples and explains them.\r\n\r\n#### Call Signatures for unions\r\n\r\nI've seen a few questions that pop-up when union signatures appear to accept intersection arguments. This was due to [this](https://github.com/microsoft/TypeScript/pull/29011). In my opinion the answer from @jcalz [here](https://github.com/microsoft/TypeScript/issues/33070#issuecomment-524561958) does a better job an motivating and explaining the change than the example in the release notes [here](https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#improved-behavior-for-calling-union-types). It would be great to see quality answers that explain _why_ something should be the way it is make their way upstream to the website (or somewhere). I don't know the best medium for this: could it be an FAQ or an example in the playground under union types?\r\n\r\n## Summary\r\n\r\nDespite this wall of text, I think the eco-system is great and I don't intend for this to be negative. I really just want to help people find all the great information _that is already out there_. I appreciate this it's also likely that you've been through this whole charade before and realise that it just isn't worth the effort: _the handbook quite clearly explains distributive conditional types yet people still ask questions about it---some people just don't read docs._\r\n\r\nI think my post can probably be summarised as:\r\n- I think information in feature PR's and release notes should not rest there, but be moved into the handbook, website examples, or somewhere else. Maybe you could ask the community to help write the extended documentation for these additions?\r\n- Be more proactive in exploiting quality answers on the tracker (or elsewhere) and updating existing resources. Particularly answers that explain the _why_, and not just the _what_. I think it would be nice to give more kudos to great answers too (on the tracker or stack overflow). Would it be reasonable to have a community highlight tweet every month that includes interesting answers by external contributors?\r\n\r\nThanks!","author":{"url":"https://github.com/jack-williams","@type":"Person","name":"jack-williams"},"datePublished":"2019-08-30T14:24:18Z","url":"https://github.com/microsoft/TypeScript-Website/issues/58"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:f7dd1a24-0d85-c864-ff9e-d2c49c03a1e4 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | EAF6:296654:7DE5C5:AAC00C:6B00DF6E |
| html-safe-nonce | bc443248c4af9e559d4254e21c7fffc0a72f29012627502ba98a28ec47e5b1fe |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFQUY2OjI5NjY1NDo3REU1QzU6QUFDMDBDOjZCMDBERjZFIiwidmlzaXRvcl9pZCI6IjcwNzU5MDcyNDU1NTY0MjQ1NTgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 0acc44818256fe2b04070ff9a78a3edd56a8b7e2285be29e68967648a0dc56a9 |
| hovercard-subject-tag | issue:487511595 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript-Website/58/issue_layout |
| twitter:image | https://opengraph.githubassets.com/26f409b9fd5c227a70ae7108123ac6044b1e5546e66cce0a1681ab89e1150a2f/microsoft/TypeScript-Website/issues/58 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/26f409b9fd5c227a70ae7108123ac6044b1e5546e66cce0a1681ab89e1150a2f/microsoft/TypeScript-Website/issues/58 |
| og:image:alt | Redirecting from the Roadmap issue. I think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could inclu... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | jack-williams |
| hostname | github.com |
| expected-hostname | github.com |
| None | 043c3f30fbcbe2c6c8e729e10cbbbc90c406546f9fbbb67c648d38f6b7d16daf |
| turbo-cache-control | no-preview |
| go-import | github.com/microsoft/TypeScript-Website git https://github.com/microsoft/TypeScript-Website.git |
| octolytics-dimension-user_id | 6154722 |
| octolytics-dimension-user_login | microsoft |
| octolytics-dimension-repository_id | 193992134 |
| octolytics-dimension-repository_nwo | microsoft/TypeScript-Website |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 193992134 |
| octolytics-dimension-repository_network_root_nwo | microsoft/TypeScript-Website |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 5425dc24e8bd8d6fca9641a12afc984825a43875 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width