Typescript: 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 https://github.com/react-native-community/discussions-and-proposals/issues/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

[sw-yx]

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

[orta]

Create a compiler error index page

The rust language does this it's quite a lot of effort to get started (TS has over a thousand errors nowadays) but the error messaging in tsc is terse, having them on a on site makes them indexable by search engines, improvable and with example code.

Tags: compiler

[andrewbranch]

What if one was able to paste a chunk of angle-rich syntax in, and observe verbose human-digestable view or a diagram

I do think this would be cool, but in some cases I think a highly structured explanation of how a type breaks down (which sounds somewhat possible to auto-generate) is not as useful as recognizing some common combinations of types and patterns that accomplish a particular goal. As an example, let’s say I want someone to explain what this is:

type X<T extends object> = {
    [K in keyof T]: T[K]
}[keyof T]

I _could_ tell you that

X is a type alias with one type parameter T who is constrained to object. When instantiated with a T, it produces a mapped type, where for each constituent K of the type keyof T, the value is the indexed access type T[K]. X then produces an indexed access type on that mapped type with type keyof T.

but it would be much more helpful, and yet extraordinarily difficult to produce by anything but a human with working knowledge of TypeScript, to tell you:

X gets the union of the types of T’s member values.

I think maybe having a collection of “recipes” of patterns like this could be handy.

[muglug]

The Advanced Types page is just a sort of dumping ground for any non-obvious type (I've stolen a bunch of TypeScript's ideas for a PHP static analysis tool, so I find myself on that page a lot).

A bunch of the ideas in there are interlinked, but that could fairly be done with hyperlinks between pages.

The Type Guard/Type Predicate section especially feels like it deserves its own page.

[southpolesteve]

Guidance for writing typescript libraries

I have found that shipping a library written in Typescript is not super easy. Lots of edge cases to consider depending on your target consumer. I have my own opinions on this that are totally up for debate, but documenting official guidance for library authors would be awesome.

Tags: libraries, guidance

[orta]

Mobile Navigation can be difficult

I can’t read the website handbook from mobile which is pretty disappointing. Also it will be great if you could have prev/next navigation at the bottom of the page on each page of the handbook.

from a tweet

Tags: nav

[Da13Harris]

Use more real-world examples

Some of the current examples are overly generic or abstract, using naming conventions that are letter-based (A, B, C) or terms that aren't relatable (foo, bar, baz, args, obj, etc). I hope to see more real-world examples (shapes, animals, products, users) and legitimate use-cases (API calls, logging, error handling, data formatting). This would be especially helpful for concepts that are already abstractions, such as Generics and Advanced Types.

Note: Some areas of the documentation already handle this issue 👌🏻 but it's hit and miss.

Tags: examples

[nojvek]

Example Library & Best Practices

Show how to type different kinds of functions. Like lodash has all kinds fancy functions like pick, extends, flatten e.t.c. Describe how to type them.

A library that incrementally builds in complexity. It could even have read more links to commits that show how a certain thing in TS is used in production.

Whatever ends up being built, I hope is very easy for someone to add examples to. I assume it will be a TS handbook like git repo.

The best open source projects usually have the best documentation and new user experience.

Let’s make TS even more welcoming for new users.

[wand3r]

Better description of tsconfig options

Current description on Compiler Options page

• Provides a very vague description of each option and how it impacts compilation and type checking. Some examples could be really useful.
• Table format leaves a little space of description
• There is no info about TypeScript version
• Alphabetical order isn't useful, some options are closely related to each other like target, module and lib or all strict like options. It is hard to get a good grasp of them when you look at them separately. You won't understand lib option without understanding target first.
• Most of the time people use those options in tsconfg files, not as tsc options so the current format could be confusing for newcomers.
• More detailed descriptions of some options are scattered across documentation e.g. @types, typeRoots and types options are described in tsconfig.json page and baseUrl and paths in Module Resolution

It is connected with Provide guides for turning on specific compiler flags suggestion, but I think the whole section needs a general overhaul. Currently, there is no guidance on how to set up configuration from start to end and there is no good glossary where you could go to find out what given option does.

edit:
Not to mention new options like the one related to building composite projects, for which there is no information in docs and you are forced to put the whole picture together based on release notes and GitHub issues.

Tags: tsconfig

[ybiquitous]

Collect documentation, blog, and other official resources to one place

If we could collect all official resources about TypeScript to one place (e.g. www.typescriptlang.org), it would be awesome! 😊

For example, the blog post about v3.5 announcement is on another place (devblogs.microsoft.com):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

And, the v3.4 release note is on another place:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

I feel this is not very useful and confusing for TypeScript developers. 😕

Tags: blog, resources

[atsu85]

create tsconfig.json by filling UI form with your preferences and project setup

It would be nice, if documentation would contain a form/wizard that helps to generate tsconfig.json that suits target environment (browser, nodeJS), user preferences (as strict or lenient as user wants) and project directory structure. Currently TS Compiler Options contain several deprecated options and some compiler flags, that from the first sight look like they might do pretty much the same thing (what are the differences between some options, for example related to paths/dirs/roots). The generated tsconfig should adhere to best practices from Microsoft TypeScript core team. Other guiding question might include:

• what is the experience of the project development team with TypeScript (might suggest "JS to TS migration path" related compiler options to novices while suggesting all strict options for "TS gurus")
• is the project a library or application (in case of library with few dependencies it may be easier to use some strict features, such as strictNullChecks, so it might be suggested depending on user experience)
• is the application using JSX/TSX (React)
• are you using framework/library, that uses decorators
  
  
  
  • should decorators metadata be emitted, so it could be used by framework/library at runtime (mention frameworks and libraries, such Angular, Aurelia as an example)
  
  

Tags: tsconfig, examples, guides, wizard, exploration

[devlato]

@orta I think it would be awesome to make a mobile version of the playground, or at least adapt the current one. As of now, the playground looks awful on mobile (the screenshot is made on iPhone 7).

[pangolingo]

I wish there was a section in the "handbook" area of the website that talked specifically about object literals and the various ways you can type them.

For instance, I'm constantly having to Google something like "typescript object literal with any properties" or "typescript object literal with one required property and any other properties".

And I always have to look up the { [key: string]: any } type, which isn't really discussed anywhere.

Some of this stuff is talked on the "Interfaces" but that's not immediately obvious.

[awinograd]

Augmenting vendor types

Sometimes when working with DefinitelyTyped types or other vendor module definitions, I find that I need to tweak the definitions to either:

1) Overwrite / modify the existing definition
2) Add a new methods / properties

I haven't been able to find documentation around the proper way to accomplish the task in different scenarios. I also haven't taken good notes when I've needed to do it myself 🐙. https://www.typescriptlang.org/docs/handbook/declaration-merging.html tackles the issue for first party code but I haven't made that advice work for third party module types/exports.

Obviously it's great to immediately open PRs to fix / update the types on the corresponding repo, but that can take a while to get merged back into the master branch which can disrupt the workflow and force adding temporary any conversions and a follow-up TODO.

Tags: vendor

[awinograd]

Compiler API documentation

The wiki has some info around using the Compiler API (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) but only shows examples of how to use it to accomplish certain goals. Would be great to have a more JSDoc style info to list the specific objects & methods that exist and learn about what they do. Right now I'm trying to learn the API and need to look at the typescript source to figure out what is going on.

(please ignore if this hasn't been done just because the API isn't yet stable as mentioned on the wiki)

Tags: compiler

[orta]

Tutorials which focus on TS by comparison to existing languages

Lots of people come to TypeScript as their 2nd (or more) language. One way to simplify learning TypeScript is by comparing it to an existing language which you already know. We could take top programming languages by popularity e.g. JS, Java, C#, PHP, C (+ CPP) and Ruby - then have directed tutorials that assume you have the knowledge of how that language works.

Right now we only make the assumption that you know JS.

Tags: tutorials

[orta]

Ensure it is accessible by default

Ensure that linters like accessibilityinsights.io pass

Tags: infra

[jordwest]

Short, shareable URLs for the playground

It'd be great if the TypeScript playground's "Share" button produced short URLs, rather than dumping the entire source code into the URL.

Alternatively, allow the URL to contain a github gist ID which populates the playground. eg: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Tags: playground

[Berkmann18]

Examples with different settings (for different use cases / scenario)

I found it tricky to get know how I could configure my TS codebase and what examples I could follow for various codebases so it would great if a list of examples like https://github.com/microsoft/TypeScriptSamples/ would feature on the website to show how one would configure the tsconfig.json and how he/she should structure TS files to work as intended.

Tags: docs, examples

[orta]

No obvious reason why docs would be in the wiki vs handbook

The page on this in the wiki is_awesome_ and I wish I had found it sooner. We should figure out what sort of things should live in the wiki (especially as it's not easily editable by anyone else (external folk have to send a PR ) ) and move the other things into the site.

[hinell]

Make better navigation between topics and titles

Huge topics like Handbook § Advanced Types have poor navigation between separate titles, no go up button either. It would be really nice to add floating navigation menu. Currently it's difficult to jump from one title to another or find out wanted one quickly.

Here is a good example of navigation given in this Assembly Script git book: https://docs.assemblyscript.org/basics/environment

Tags: website, handbook, navigation

[AnyhowStep]

Mobile Friendly Playground Code Editing

As I understand it, mobile-friendly code editing with syntax highlighting and all the other IDE features is a pain.

However, I've found myself wanting to play with code snippets while on my phone, away from a desktop/laptop, quite often.

I wouldn't mind a plain <textarea> field, instead of a syntax highlighted editor for mobile use.

The errors could possibly be on another page or a popup or some other html element.

Tags: playground, mobile, code editor

[David-Else]

Document adding the .js extension for browser compatible es6 modules

There is no mention anywhere that TypeScript can be used perfectly well to generate es6 modules that work in the browser by simply adding the .js extension to the name of the import! The only place this info seems to exist is in this thread:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment-343610106

Not sure which version of TS added it, but imports such as './file.js' now work (even if the file is actually file.ts).

For me this was a massive feature... but officially it does not exist?!

[eugirdor]

Advanced Types page does not include Omit<T, K> type.

Omit<T, K> was recently added in TypeScript 3.5, but the Advanced Types page still has the following disclaimer:

Note: The Exclude type is a proper implementation of the Diff type suggested here. We’ve used the name Exclude to avoid breaking existing code that defines a Diff, plus we feel that name better conveys the semantics of the type. We did not include the Omit type because it is trivially written as Pick>.

[Jojoshua]

Provide project setup documentation for Linters

As part of setting up a project, include how to setup with a Linter, most likely just typescript-eslint which the project is supposed to be using itself.

Tags: linter

[threehams]

There is nothing covering the most commonly-hit errors or TypeScript limitations.

When you're first learning TypeScript, there are certain patterns which aren't + won't ever be supported in TypeScript. One of the simplest:

const buildResult = (name?: string) => {
  const result = {};
  if (name) {
    result.name = name; // error, this property doesn't exist on {}
  }
  return result;
};

I've started introducing TypeScript to my company, and cases like this pop up a lot, so I've started documenting them in a FAQ/troubleshooting style of guide. It's growing quickly (note that this is in a rough state):

Building up an object one property at a time
Why you're not getting errors when you want them: excess property checking
How to access optional properties, including from unions
Why Object.keys and Object.entries don't do what you want
Making filter filter, making reduce work without errors
Type refinement being lost

If any of this information is in the docs, I haven't been able to find it. I've only understand these through years of trial/error, and reading through the most-linked issues on Github.

Tags: errors, troubleshooting, limitations

[Tschrock]

Provide clear documentation on how to add custom type definitions

There are a number of libraries which don't include types, and which don't have an @types/* package available. I'd like to be able to write my own declaration files for these inside my project, but there doesn't seem to be any documentation on the 'right' way to write them and get typescript to recognize them. Say I'm importing a module from npm. Do I need to use declare module x? or declare module "x"? or use a namespace? or just export the types? Is there a specific place I need to put these files? What config options do I need to set? typeRoots? types? paths? include? or what? - all I've found so far are confusing error messages, poorly explained config options, and outdated SO questions.

Tags: docs

[hinell]

Lack of offline documentation

Modern basic dev tools like git or npm have their own subset of commands that allow us to access offline documentation/reference e.g.:

$ git help ls-remote
$ npm help search 

I think it would be nice to have such feature (even though the TS is a little bit different).
It would allow us to explore docs locally via help like command without need to refer to the site/github etc:

$ tsc help tsc # basic CLI arguments desc
$ tsc help config # opens up html page of the tsconfig.json docs
$ tsc help v3.5 # opens up html page changelog
$ tsc help enum # finds pages containing `enum` type and hints their names/opens them up

Tags: offline, search, cli, local

[waynevanson]

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.

[orta]

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

1. Tailored introductions (setup for the core handbook)
   
   
   
   1. The core handbook (everyone reads this)
   
   
   2. 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!

[mihailik]

Awesome work thanks a lot @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.

[orta]

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.

[jcalz]

@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?)

[dragomirtitian]

@orta @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.

[orta]

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.

[Tyler-Murphy]

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.

[ssalka]

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

[orta]

@Tyler-Murphy we've fixed that now

@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 👍

[simeyla]

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

[Shinigami92]

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

[ssalka]

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!