Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
orta opened this issue Jun 19, 2019 · 43 comments

Comments

Projects
None yet
@orta
Copy link
Member

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

"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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

@sw-yx

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jun 19, 2019

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.

image

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jun 19, 2019

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.

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

image

@mihailik

This comment has been minimized.

Copy link
Contributor

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member

commented Jun 19, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 19, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

@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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link

commented Jun 20, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 20, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 20, 2019

Ensure it is accessible by default

Ensure that linters like accessibilityinsights.io pass

Tags: infra

@jordwest

This comment has been minimized.

Copy link

commented Jun 21, 2019

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

This comment has been minimized.

Copy link

commented Jun 21, 2019

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

This comment has been minimized.

Copy link
Member Author

commented Jun 21, 2019

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

This comment has been minimized.

Copy link

commented Jun 21, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jun 22, 2019

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

This comment has been minimized.

Copy link

commented Jun 25, 2019

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:
#16577 (comment)

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

This comment has been minimized.

Copy link

commented Jun 25, 2019

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<T, K> type because it is trivially written as Pick<T, Exclude<keyof T, K>>.

@Jojoshua

This comment has been minimized.

Copy link

commented Jun 28, 2019

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

This comment has been minimized.

Copy link

commented Jul 2, 2019

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

This comment has been minimized.

Copy link

commented Jul 6, 2019

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

This comment has been minimized.

Copy link

commented Jul 8, 2019

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

This comment has been minimized.

Copy link

commented Jul 19, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.