René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:f7dd1a24-0d85-c864-ff9e-d2c49c03a1e4
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idEAF6:296654:7DE5C5:AAC00C:6B00DF6E
html-safe-noncebc443248c4af9e559d4254e21c7fffc0a72f29012627502ba98a28ec47e5b1fe
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFQUY2OjI5NjY1NDo3REU1QzU6QUFDMDBDOjZCMDBERjZFIiwidmlzaXRvcl9pZCI6IjcwNzU5MDcyNDU1NTY0MjQ1NTgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac0acc44818256fe2b04070ff9a78a3edd56a8b7e2285be29e68967648a0dc56a9
hovercard-subject-tagissue:487511595
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript-Website/58/issue_layout
twitter:imagehttps://opengraph.githubassets.com/26f409b9fd5c227a70ae7108123ac6044b1e5546e66cce0a1681ab89e1150a2f/microsoft/TypeScript-Website/issues/58
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/26f409b9fd5c227a70ae7108123ac6044b1e5546e66cce0a1681ab89e1150a2f/microsoft/TypeScript-Website/issues/58
og:image:altRedirecting 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:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamejack-williams
hostnamegithub.com
expected-hostnamegithub.com
None043c3f30fbcbe2c6c8e729e10cbbbc90c406546f9fbbb67c648d38f6b7d16daf
turbo-cache-controlno-preview
go-importgithub.com/microsoft/TypeScript-Website git https://github.com/microsoft/TypeScript-Website.git
octolytics-dimension-user_id6154722
octolytics-dimension-user_loginmicrosoft
octolytics-dimension-repository_id193992134
octolytics-dimension-repository_nwomicrosoft/TypeScript-Website
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id193992134
octolytics-dimension-repository_network_root_nwomicrosoft/TypeScript-Website
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release5425dc24e8bd8d6fca9641a12afc984825a43875
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/microsoft/TypeScript-Website/issues/58#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmicrosoft%2FTypeScript-Website%2Fissues%2F58
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmicrosoft%2FTypeScript-Website%2Fissues%2F58
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=microsoft%2FTypeScript-Website
Reloadhttps://github.com/microsoft/TypeScript-Website/issues/58
Reloadhttps://github.com/microsoft/TypeScript-Website/issues/58
Reloadhttps://github.com/microsoft/TypeScript-Website/issues/58
microsofthttps://github.com/microsoft
TypeScript-Websitehttps://github.com/microsoft/TypeScript-Website
Codehttps://github.com/microsoft/TypeScript-Website
Issues58 (58)https://github.com/microsoft/TypeScript-Website/issues
Pull requests166 (166)https://github.com/microsoft/TypeScript-Website/pulls
Actionshttps://github.com/microsoft/TypeScript-Website/actions
Security and qualityhttps://github.com/microsoft/TypeScript-Website/security
Insightshttps://github.com/microsoft/TypeScript-Website/insights
https://github.com/microsoft/TypeScript-Website
New issuehttps://github.com/login?return_to=https://github.com/microsoft/TypeScript-Website/issues/58
New issuehttps://github.com/login?return_to=https://github.com/microsoft/TypeScript-Website/issues/58
How to capture FAQ's, Gotcha's, and other useful TypeScript details.https://github.com/microsoft/TypeScript-Website/issues/58#top
https://github.com/jack-williams
Jack Williams (jack-williams)https://github.com/jack-williams
on Aug 30, 2019https://github.com/microsoft/TypeScript-Website/issues/58#issue-487511595
herehttps://github.com/microsoft/TypeScript/pull/18654
herehttps://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html
Here https://github.com/microsoft/TypeScript/issues/33025#issuecomment-524053918
Wesley Wigham (@weswigham)https://github.com/weswigham
linkhttps://devblogs.microsoft.com/typescript/announcing-typescript-3-5/
thishttps://github.com/microsoft/TypeScript/issues/31672
thishttps://github.com/microsoft/TypeScript/pull/29011
Joe Calzaretta (@jcalz)https://github.com/jcalz
herehttps://github.com/microsoft/TypeScript/issues/33070#issuecomment-524561958
herehttps://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#improved-behavior-for-calling-union-types
https://github.com/jack-williams
Jack Williams (jack-williams)https://github.com/jack-williams
on Sep 1, 2019https://github.com/microsoft/TypeScript-Website/issues/58#issuecomment-526927611
https://github.com/orta
Orta Therox (orta)https://github.com/orta
on Sep 1, 2019https://github.com/microsoft/TypeScript-Website/issues/58#issuecomment-526943841
https://user-images.githubusercontent.com/49038/64078700-cf3f0b00-ccab-11e9-9b45-ff7f97d2782b.png
https://github.com/jack-williams
Jack Williams (jack-williams)https://github.com/jack-williams
on Sep 2, 2019https://github.com/microsoft/TypeScript-Website/issues/58#issuecomment-526965934
https://github.com/jack-williams
Jack Williams (jack-williams)https://github.com/jack-williams
on Sep 4, 2019https://github.com/microsoft/TypeScript-Website/issues/58#issuecomment-528111928
Jack Williams (jack-williams)https://github.com/jack-williams
completedhttps://github.com/microsoft/TypeScript-Website/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
on Sep 4, 2019https://github.com/microsoft/TypeScript-Website/issues/58#event-2608662479
Sign up for freehttps://github.com/signup?return_to=https://github.com/microsoft/TypeScript-Website/issues/58
Sign in to commenthttps://github.com/login?return_to=https://github.com/microsoft/TypeScript-Website/issues/58
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.