What do you not like about the TypeScript Website and Documentation?

[orta]

What do you not like about the TypeScript Website and Documentation?

Hey folks, we, the TypeScript team at Microsoft, are planning a full re-think of our website to match our revised handbook. The team has a lot of our own ideas about the current deficiencies of the site and what we'd like to improve, but we also want to open the floor to others to pitch ideas.

We saw a format which worked well for these sorts of discussions from the React Native team in react-native-community/discussions-and-proposals#64 which is for people to reply to this issue with a single idea per comment.

Please do reply with 1 comment per issue which you are having with the website, documentation, resources, process, playground etc. Add tags if you'd like to help with search for others and ease-of classification. If you have a link to an existing issue, that would be super useful too.

If you see that someone has already pitched your idea, please use the emoji reactions to +1 it, we will be deleting duplicates and off-topic replies. If you want to add more to a topic, see if it has an attached issue and leave more feedback there.

Please do not use this thread for discussions about the TypeScript language itself, and as with all issues please conform to the code of conduct. We all want to see improvements.

Template - feel free to copy & paste

### [title]

[message]

Tags: `[tags]`

For example

One of mine:

---

Website is closed source

I would like to contribute fixes and improvements, but because I don't have the ability
to do this while the repo is private

Tags: oss

---

[wongmjane]

"Utility Types" page not up-to-date

New utility types are often missed or not added to the "Utility Types" page of the handbook (e.g. Parameters<T>). I often have to resort to browsing lib.es5.d.ts instead of the handbook.

Tags: docs

[orta]

Official TypeScript Playground isn't as good as open-source alternatives

https://typescript-play.js.org does a better job than the official one: it covers multiple versions of TypeScript, allows sharing larger texts, it supports all compiler flags and strict mode is on by default.

Tags: playground

[wongmjane]

Lack of index page for Release Notes

I wish there will be a index page to list all past Release Notes under this URL: https://www.typescriptlang.org/docs/handbook/release-notes. That way, we can keep track of the past release updates on TypeScript.

Tags: docs, release notes

[orta]

There isn't a glossary of type names

If you passed someone code like const a: "foo" | "bar" you might not know to call this a Union Type.

This one is a pretty low bar, but when we start talking about existential/conditional/mapped/etc types it's nice to be able to go to a page that just tries to define it, but not document it deeply so you can get an overview of all the taxonomy for this language

Tags: types, handbook

[orta]

There isn't a page to share with non-technical folk

This one I needed to initially persuade people outside of engineering (think PMs, non-technical Managers) what the value in using TypeScript is. In the end I wrote this myself but would prefer an official

Tags: guides

[orta]

Definitely Typed documentation lives outside of the TypeScript docs and is out of date

The TypeScript project should own docs around this. The documentation for Definitely Typed lives in:

• https://definitelytyped.org
• https://github.com/DefinitelyTyped/DefinitelyTyped#how-can-i-contribute

The TS docs could contain an overview of what it is, why it's used and we can deprecate the official site

Tags: definitely-typed

[swyxio]

doesnt progressively teach TS

(Edited for more readability) I feel that docs are most effective when they have a clear "persona" they are meant for. When these docs were created, ES6 was not yet a thing. When these docs were created, you could learn all of TS in an afternoon.

Times have changed.

I made react-typescript-cheatsheet bc i felt the TS docs specifically did not serve people who already knew es6 and also didnt want to learn advanced TS all in one go. so specifically targeting the experienced JS dev trying TS out for the first time. theres a lot of us‬. The current docs are either “hey here’s what classes are” or “heres a bunch of scary looking generics on the same page as our type operator docs”.

in particular here is a non exhaustive list of personas to consider that could serve as a progressive teacher:

• people who just want to use TS with JSDoc, no build step
• people who want to use TS without writing any generics as much as possible
• people who are migrating codebases from JS/Flow to TS
• people who are new to TS, adopted TS, but see unfamiliar, verbose errors for the first time and have no idea how to deal with it (this is the "troubleshooting" audience) or opt out of it
• people who want to publish TS libraries vs TS apps
• people who want to learn to use type operators
• people who want to learn about type utilities that may help them
• people who need to type untyped libraries (it is very much a network effect and an interest of TS to make .d.ts writing as ridiculously easy and well documented as possible)
• and aaaaaaalll the way at the end, people who want to learn how to write their own generic type logic
• (maybe) people who want to write plugins that need to traverse TS AST

These are all stages in the adoption journey of TS, we should map it out and make sure that there isn't some cliff in the docs where people fall off because they dont know what to do and therefore assume it is too hard.

I think the docs can do a lot to help dispel the myth that:

• you need maximum type safety at all times (not just in tsconfig, but also in the choices we make in typing functions)
• TS is for OO programmers (yes, i have seen this)
• TS is only for C#/Java devs who come to JS and miss types, it has no real value for JS devs
• you should be able to figure out how to resolve TS errors on your own
• in general, that TS has a high learning curve to get started

if resources are available, we can and should target specific large dev communities to assist their adoption, e.g. for React but also Vue and also Node and so on. You can do this off of the main docs, for example Vue docs make a distinction between Cookbook and Guide focusing on practical examples in context.

this is probably as big a hurdle to late-stage TS adoption (i.e. people who require more docs/tools/assurance/handholding in order to be sold on TS) as i can imagine.

tags: docs

[MartinJohns]

Linked TypeScript Language Specification is completely out of date

Directly on the main page you're linking to the "TypeScript Language Specification".

Read the specification on GitHub or download it as a docx or pdf.

However, that specification is completely outdated (stuck at version 1.8, last real update at January 2016), and it's not maintained. It would be best to drop any mention of the specification.

Tags: spec specification outdated

[mihailik]

Playground-like widget for code samples

Present all the code samples in docs in a playground-like widget, with all the convenient tooltips, highlights etc.

Ideally with ability to pop out into a full playground, with editing and looking at emitted JS/typings.

This would naturally rely on Official TypeScript Playground isn't as good as open-source alternatives suggestion.

[pshrmn]

API documentation that only exists in release notes

Some types, e.g. unknown, are only documented in the release notes, which makes them difficult to discover.

Tags: docs

[mihailik]

Fourslash playground

There's an awful lot of files in /tests/cases/compiler that, together with baselines behave like cryptic dark matter. These megabytes could be reused as docs/demos.

• make TS playground load any file from TS repo via something like: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• make TS playground understand 'fourslash'
• add descriptive comments to those files

That would both allow someone to URL-link to interesting syntax cases, and help people tinker and submit other funky tests.

[mihailik]

Playground that EXPLAINS a given TS syntax

It's not hard to stumble upon a convoluted TS syntax that is really hard to comprehend. Recursive generics, combined via unions and funky indexed types... One big nest of such scary centipedes is typings, for example.

What if one was able to paste a chunk of angle-rich syntax in, and observe verbose human-digestable view or a diagram. You know, where you can undoubtedly clearly see that A is a class, and B is a union type, and C is a generic parameter for D and so on.

Starting as naive 'verbose AST pretty-print' this can with time and community contribution expand both into deeper pattern recognition and into richer interactive visuals and UML-like diagrams.

[Haroenv]

there’s no search for the documentation

I often have to resort to googling how to do something with typescript rather than having the main doc as a source of truth, eg with DocSearch like on the React docs

Tags: search, exploration

[orta]

Highlight community projects

This could be things like meetups, community talks or books.

But could also larger software projects which use TypeScript that someone could learn from.

Tags: Community

[orta]

Provide guides for turning on specific compiler flags

E.g. if I were to turn on noImplicitReturns what sort of issues would I hit, and how should I handle them? We ship these sorts of recommendations with the version release notes for the time those flags were introduced, and so looking them up is tricky.

Tags: tsconfig