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.
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).
Search “typescript generics syntax” and you get the excellent TypeScript docs on generics as the first result. It covers generic constraints.
Indeed, but I'm not sure how that's relevant since it doesn't cover generic parameter defaults.
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.
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.
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.
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.
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".
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.
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.
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).
But I am fairly certain that like the Perl documentation and unlike Java and Spring docs none of them was infuriating.