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

"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

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

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

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

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

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:

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

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

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

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.

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

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.

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.

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

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

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

The examples need some better distinguishing colours!

How it should be:

const whomstve = (name: string) => name + 'is life'

How it currently is:

const whomstve = (name: string) => name + 'is life'

There is a bit of blue, but that's it.

Hi folks, I’ve been keeping an eye on this issue while having a think about the general site structure and overall documentation over the last month. Now that this issue has settled down, and I've got a bit more understanding on what I'd like the docs to look like.

Let’s try look through all of these points based on reactions, with a bit of shuffling for readability.

API docs can sometimes only exist in release notes

This one will be tricky, in part because right now I’m not certain what only lives in the release notes.

With respect to the language and syntax, I’d expect this to be fixed and improved with the new upcoming handbook which is taking a fresh look at the entire language. For the rest of the documentation, I think some of the new sitemap should cover most of the cases - but it's still a WIP

No search on the website

Yeah, I agree, this one is definitely critical for the new site.

The website is closed source

Fixed! https://github.com/microsoft/TypeScript-website

The new work will go off the master branch, but for now the old site is accessible above and taking PRs. I’ve been moving issues from the TypeScript repo over to here too, so it’s easier to keep track of them all.

Utility Pages not up-to-date

Fixed! In part I merged a lot of PRs, and got the current handbook up to date from the community. As well as making sure that it would show up in the nav (instead of from a web-search only)

Improved TS Config option descriptions

I started exploring this over the weekend (how can we ensure that the compiler and website share the same initial datasource for these docs, and what can the website build on-top of that to provide more context)

Some examples of direction so far:

my own notes from 2017
I’ve been chatting with Ethan Arrowood Matterhorn (@MatterhornDev) whose tsconfig-ui could be the foundation for creating a TSConfig explorer

Playground isn’t as good as alternatives

Fixed! I consider this a positive stepping stone in the general direction which I’d like the playground to be. I’ve got some example mockups that provide a more long-term perspective on what the Playground should look and feel like to make it truly best of breed.

(click for figma explorations)

Short sharable URLs for playground

Fixed, see below

No glossary of type names

I’ve started writing my own, as I learn the compiler - I’d expect to see this feed into the new handbook. It also affects the playground examples, which serves as a glossary of examples for some of the more advanced types

[playground ex1, playground ex2]

Doesn’t progressively teach TS

This is aimed to be addressed in the new handbook, to quote some of #29288 (scroll to New handbook)

Writing a general document for all users is difficult because the audience for TypeScript is broad, and one of the strengths (and weaknesses) of the current handbook is that it tries to serve everyone at once. We have several different groups of developers who have different expectations when learning TypeScript, and we need to adjust the level of exposure of different concepts. Given that, our goal is to organize the handbook into three different parts:

Tailored introductions (setup for the core handbook)

The core handbook (everyone reads this)

Reference pages (kind of like deep-dives/appendices)

Effectively it has a few different starting points and then tries to teach the language once you’ve got familiar with the surrounding eco-system.

Does that address everything in the comment? No, just the start. The current sitemap I have is pretty extensive, and these are the types of problems I’m interested in

I’ve left some wiggle room in my current site-map cookbooks and guides, with cookbooks being something that we can encourage more community support with.

Provide Guides

I’ve taken the time to start sorting out and updating the current code-samples which are currently on the TypeScript website. I’m still figuring out which samples are better left on our side vs re-directing to the official documentation (for example if a project now natively supports TypeScript, and they have their own docs)

As with above, I think the cookbooks and actual guides section of the site should be enough to cover this

Language Spec is out of date

Yeah, I don’t know if I can remove it outright from the main repo - but it won’t be mentioned on the new site.

Provide better IDE-like experiences for code samples

This is currently in with the new handbook site, though we’ll have to port it over to the new site too. It also provides highlighting and inline error messaging, which I’m excited about.

Compiler error index page

Not certain if this one will happen, in part TypeScript has a lot of error codes and they’re changing pretty regularly. It’s worth coming back to once there’s a fully working site and docs, but for now it’s on the back burner.

Show more real-world examples

The new handbook so far is doing a good job at this 👍🏾 - we can aim to keep it that way. With the rest of the docs, I’ll try change anything I see to be that way.

Mobile support in site is weak

I’m looking at using the Microsoft design system (fluid) for the new site, which should mean that mobile support (with accessibility) should come “for mostly free”

With something as complex as the playground that’s a tad trickier, I think for phone-sized mobile a browsing/exploration mindset is a good fit. So, I have a mockup of that being a little closer to a read-only experience:

Explore tsc help improvements

I’m open to this, but the typescript CLI is really only one command, compile (which is why there’s no need for help on subcommands (though --init kinda breaks that))

Provide advice on improving DTS

Yeah, I’m planning on merging the definitely typed website into the typescript website and consolidating those docs. Whether all of them will live in the site is still up for debate. There’s some good reasoning to keep the actual implementation details of contributing in the definitely typed repo, while the high level overviews can live in the site.

Consolidate docs/blogs/releasenotes

A tricky one, I don’t quite have an answer for the blog/release notes. We use the Microsoft product blogging system with everyone else, and I’m not sure if it’s a good idea to move all of that into the website itself. We can figure that one closer to the time.

On the easier side, I definitely would like to remove this sort of information from the wiki and leave it only inside the website (where it can get indexed by the site search) - I’d like to leave the TypeScript wiki specifically for contributing to TypeScript and working with the TypeScript compiler APIs (e.g. when you import * as ts from “typescript”, or build a language server plugin)

Cover most commonly-hit errors

This relates to the above - there’s a really extensive FAQ page for these sorts of problems, which I only just discovered in the wiki (3 years into my usage of TS).

We can take this as a baseline and start to pull them into the main website with your responses too

Add syntax highlighting

Yep agree, thanks!

All in all, I think we've got a lot of these being actively explored or worked on, and I'm open for more feedback as we keep on working on docs!

Orta Therox (@orta)

Awesome work thanks a lot Orta Therox (@orta) !

How about borrow/improve/collaborate with VSCode tsconfig experience in the Playground editor, instead of create a separate one?

Makes the Playground better, and the existing experience in VSCode is already half-decent.

I'm not really sure what you mean. Like the auto-complete JSON schema features in VS Code? I was planning on having that in the JSON editor part, but an overview of every option as a GUI with labels is a useful way to see all of the options and pick and choose.

Orta Therox (@orta)

Orta Therox (@orta) When the new handbook becomes the official handbook, will URLs pointing to sections of the current handbook break? Or will the new handbook be at a different URL? I'm just wondering because I've put scads of handbook links in SO answers over the last several years (I'm sure others have done this too) and it would be unfortunate if they all broke. (Is there a better issue or location to talk about general documentation migration plans?)

Orta Therox (@orta)

Orta Therox (@orta) Joe Calzaretta (@jcalz) Was wondering the same thing, I have over 2.5K SO answers, finding all answers with links and updating them all is just not feasible. Ideally links with fragments would still work and redirect to new locations. I am willing to help with the mapping if needed.

Yep, I don't believe in breaking URIs - there's a few options to explore.

I think it's likely going to be using a new URL root for the handbook (e.g not docs/handbook/x.html but maybe /handbook/x.html), and making the older pages re-direct to their closest equivalent via a map of some sort.

I'd like to know what all of the github labels for this repository mean. Some of them are self-explanatory, but others aren't.

For example, "Needs Proposal" is unclear to me. It'd help for all of the labels to have longer descriptions like some already do.

Can't link to docs for specific compiler options

My team is relatively new to TypeScript, and as such, our tsconfig.json is frequently changing, and oftentimes I want to point people to the documentation for specific compiler options, i.e. in the form of:

https://www.typescriptlang.org/docs/handbook/compiler-options.html#strict-null-checks
(or)
https://www.typescriptlang.org/docs/handbook/compiler-options.html#strictNullChecks

Links like this don't work, but I would like them to.

Currently the only HTML id I can see on that page is #compiler-options, which is not that useful as it is basically at the very top - having an id for each of the options, however, would be very helpful for getting people to the desired part of the page.

Tags: compiler

Tyler Murphy (@Tyler-Murphy)

Tyler Murphy (@Tyler-Murphy) we've fixed that now

Steven Salka (@ssalka) - yeah, good call that will be in the new tsconfig docs

--

I'm going to close this issue, I'll re-open a new one in the future with the same premise once we've got further into the handbook and new site 👍

Typescript Playground:
I feel like I'm going crazy but I can't find a simple 'Share' option to save and share my project (eg. to add to a github issue).
I see all the links under 'Export' but no 'Share'.

Typescript Playground:
I feel like I'm going crazy but I can't find a simple 'Share' option to save and share my project (eg. to add to a github issue).
I see all the links under 'Export' but no 'Share'.

Example: Playground Link

The new site looks really nice! However I noticed this request (anchor links for compiler options) did not make it in 😕

Seems like it would be a really easy request to accommodate and would be very helpful for newcomers. Hope to see it in a future update!

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

Description