[hmsimha]

Yes, and a great way to do that is to read documentation, of which Typescript is frequently lacking. For example, I got a suggestion in the discord recently to use "generic parameter defaults" for a problem I was having, which were documented... in the release notes for Typescript 2.3... and no where else: https://www.typescriptlang.org/docs/handbook/release-notes/t...

[benced]

I love Typescript but I just don’t think this is correct. Look at the Node documentation and then the Typescript documentation. The former tries to describe every behavior, the latter tries to give you a 101 in the feature. This is especially clear when it comes to the Deno and SWC teams’ attempts to reimplement tsc in a faster language - typescript doesn’t have a spec so they’re stuck looking at the tsc codebase to infer behavior.

[hmsimha]

I think you intended this as a reply to someone else. Or at least, it sounds like you're agreeing with me.

[arinlen]

> Yes, and a great way to do that is to read documentation, of which Typescript is frequently lacking.

I completely disagree, and I was surprised by this sort of comment.

Find me a single programming language whose docs are as good as TypeScript's docs and reference. I'd be surprised if you could come up with a single example.

[hmsimha]

I think others have covered it here, but I want to point out that I actually think Typescript's docs are quite good for end-users! But, like the article here points out, lacking, for library authors.

There are lots of ways to do things that you kind of just have to learn from reading blog posts, or reading code and then asking in the discord when you see something undocumented (because have you tried googling "what does <T=...> in Typescript mean"?).

Ideally, at the very least, all syntactic features and keywords of the language should be documented, but it's more than that; Typescript is a metalanguage, and authors of many libraries have also developed patterns which are essential for describing complex types. Some of these patterns are documented (for example, discriminating union), and some are not (for example, opaque types). And some features which are documented could do with a lot more exposition and functional examples ("as const"), or notes on when to avoid (enum).

[Smaug123]

First hit for "Typescript equals in generic" is https://stackoverflow.com/questions/56843790/typescript-gene... which explains it. No search results in the docs, sure, but the very first hit for the first query I tried gave me the answer.

[account-5]

Whilst that's good, the TS documents should document this. Google searching and stackoverflow is not a valid replacement for actual documentation, IMO.

[Smaug123]

Certainly they should document it, but as an answer to "(because have you tried googling "what does <T=...> in Typescript mean"?)", I think it seems pretty conclusive :P

[atwood22]

> because have you tried googling "what does <T=...> in Typescript mean"?

Search “typescript generics syntax” and you get the excellent TypeScript docs on generics as the first result. It covers generic constraints.

[hmsimha]

> It covers generic constraints.

Indeed, but I'm not sure how that's relevant since it doesn't cover generic parameter defaults.

[rhacker]

C#, C++, Java (actually I am betting no one can beat that one)

I think you dismissed the actual issue he faced- gen type defaults, which I just looked is still not actually documented, it's just in the release notes.

Don't get me wrong, TS is my favorite language, but let's not gloss over things.

[philliphaydon]

My career has been 95% c#.

Recently learning rust (spare time) and c++ for work. The documentation for these 2 are awesome!

PostgreSQL has great docs too

I think we are better at writing docs for programming languages than we are at libraries and frameworks. Maybe because languages are more ‘fixed’ and less likely to change so over time they just get better and better.

[inferiorhuman]

You picked two of the best documented projects around in Rust and PostgreSQL. I don't think that inferior documentation for libraries is a foregone conclusion. Rust's serde library is exceptionally well documented IMO.

It's a matter of having the skill and the will though, and I feel like a lot of projects simply don't emphasize documentation. Even so, not everyone's going to be a good technical writer.

[philliphaydon]

What I mean is I think in general languages tend to have better docs.

Vue has excellent docs imo.

But in terms of technical writing being a skill. I agree. I appreciate the effort people put into docs. I try my best but I’m not very good. So I have a lot of respect for anyone who can sit and write excellent docs.

[inferiorhuman]

It's been a long time since I've dug for C++ docs but in general I found Qt to be well documented (if a bit disorganized with the newer stuff). STL documentation always seemed inaccessible to me, but then again I'm working off of some pretty hazy memories.

[rendaw]

> Find me a single programming language whose docs are as good as TypeScript's docs and reference.

This is a non sequitur. Typescript can be bad even if other languages are worse.

The argument being made in the article and this discussion isn't "use X instead of Typescript" it's "Typescript should be improved".

[afarrell]

Is the argument "Typescript should be improved" or "We should allocate enough time/money from other things to improve Typescript"?

The former is vacuously true once you know it is an option. Everything would be better if it could be improved.

The latter is subject to questions about cost. If Typescript had best in its class docs, that would imply that other communities had failed to find or execute a practical option to turn time/money into docs improvements. That would be moderately persuasive evidence that Typescript's resources are better spent elsewhere.

---------

On an object level: Django and the python community tend to have great docs.

[rendaw]

It could also be about refocusing within the Typescript project.

[u8]

Golang has https://pkg.go.dev. Rust has https://docs.rs

Golang entire standard library is documented. Plus with how the language is designed docs don’t need to change with new versions. Just with new functions.

[mook]

More importantly, golang has https://go.dev/ref/spec — most of the time I wished for better TypeScript documentation it's about syntax (though I did need to go read the default bundled libraries a couple times for details, that's rarer).

[eitland]

PHP used to have amazing documentation back in the days.

Everything spelled out. No "you must read the whole thing or have worked with it for years to understand page 5".

Plenty of inline examples and even more user submitted ones (although as with all user generated content, some caution should be used when reading those).

[Tijdreiziger]

Have we used the same PHP? IME it's usually necessary to read the comments on the documentation for important information, which is frequently totally absent in the actual documentation.

[eitland]

Haven't used PHP seriously for a decade I think so I might have a bit of rose tinted glasses.

But I am fairly certain that like the Perl documentation and unlike Java and Spring docs none of them was infuriating.

[stevage]

JavaScript

[0xfffafaCrash]

https://www.typescriptlang.org/docs/handbook/release-notes/o...