How to capture FAQ's, Gotcha's, and other useful TypeScript details.

[jack-williams]

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 properties of TypeScript, slightly more detail on certain type relationships, or some of the heuristics TypeScript uses to skip expensive checks.

In 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?

There 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^*hope that we can improve the situation here.

I 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).

FAQ or Gotcha: Strict function types and methods.

I'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, and the release notes for that version of TypeScript here. AFAIK this isn't document in the handbook or FAQ.

My 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?

Interesting TypeScript details lost in the tracker.

There 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:

Why is keyof never should be string | number | symbol?

Here 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.

Behaviour of writing to an indexed access type.

There 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. If you follow many of the related issues such as this 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.

Call Signatures for unions

I've seen a few questions that pop-up when union signatures appear to accept intersection arguments. This was due to this. In my opinion the answer from @jcalz here does a better job an motivating and explaining the change than the example in the release notes here. 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?

Summary

Despite 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.

I think my post can probably be summarised as:

• 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?
• 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?

Thanks!

[jack-williams]

Perhaps a modest change would be to have a good network of related links, which looking at the update playground examples, I think is already part of the plan. Something like:

• An FAQ that is broken up into pages/sections that have similar titles to sections in the handbook and playground.
• Point each example in the playground to the relevant handbook page.
• Point each handbook page to the relevant FAQ page.

[orta]

Could there ever be a call for documentation associated with a merged feature PR which is shepherded by someone in the team?

I think it could be quite reasonable that we add a "needs docs on release" label to every PR which necessitates me running through adding docs in the right places when we ship the RC/Beta. I think the most labour intensive part would be the hyperlinking between everything, and transforming the code samples in the PR from foo bar-y to something relatable to everyone.

This roughly is my eventual site-map for a v2 (which I want to get to incrementally):

What questions could look like, what kinds of sections, how we/submitters determine it being worth putting on the site and how we can promote it is definitely up in the air

[jack-williams]

The roadmap and new playground examples look great.

Yeah coming up with examples is hard; hopefully if the feature is popular enough there are lots of linked issues with 'reasonable' examples.

[jack-williams]

Closing this up. If there are any actionable and well-defined tasks they can be created in new issues.