4 ms·

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

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/typescript-2-3.html#generic-parameter-defaults https://www.typescriptlang.org/docs/handbook/release-notes/t...

arinlen 4y ago
> 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.
- stevage 4y ago
  JavaScript
- rhacker 4y ago
  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 4y ago
    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 4y ago
      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 4y ago
        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 4y ago
        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.
        jacobr1 4y ago
        Commercially supported software Qt (and in the parent post, Vue) tend to have good docs. It makes sense: supporting developers is their business model. Likewise tools with ecosystems of companies (postgresql) tend to get good docs over time. The bigger pain points are tools supported by a major company ... but that used by the business rather than sold. There probably are _some_ good docs - especially at the project launch or major milestones - but they aren't as actively curated.
- hmsimha 4y ago
  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).
  - atwood22 4y ago
    > 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 4y ago
      > It covers generic constraints. Indeed, but I'm not sure how that's relevant since it doesn't cover generic parameter defaults.
  - Smaug123 4y ago
    First hit for "Typescript equals in generic" is https://stackoverflow.com/questions/56843790/typescript-generic-type-with-equal-operator-means 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 4y ago
      Whilst that's good, the TS documents should document this. Google searching and stackoverflow is not a valid replacement for actual documentation, IMO.
- u8 4y ago
  Golang has https://pkg.go.dev https://pkg.go.dev. Rust has https://docs.rs 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 4y ago
    More importantly, golang has https://go.dev/ref/spec 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).
- rendaw 4y ago
  > 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 4y ago
    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 4y ago
      It could also be about refocusing within the Typescript project.
- eitland 4y ago
  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 4y ago
    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 4y ago
      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.
benced 4y ago
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 4y ago
  I think you intended this as a reply to someone else. Or at least, it sounds like you're agreeing with me.
0xfffafaCrash 4y ago
https://www.typescriptlang.org/docs/handbook/release-notes/overview.html#generic-parameter-defaults https://www.typescriptlang.org/docs/handbook/release-notes/o...

arinlen 4y ago

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

stevage 4y ago
JavaScript
rhacker 4y ago
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 4y ago
  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 4y ago
    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 4y ago
      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 4y ago
        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.
        jacobr1 4y ago
        Commercially supported software Qt (and in the parent post, Vue) tend to have good docs. It makes sense: supporting developers is their business model. Likewise tools with ecosystems of companies (postgresql) tend to get good docs over time. The bigger pain points are tools supported by a major company ... but that used by the business rather than sold. There probably are _some_ good docs - especially at the project launch or major milestones - but they aren't as actively curated.
hmsimha 4y ago
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).
- atwood22 4y ago
  > 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 4y ago
    > It covers generic constraints. Indeed, but I'm not sure how that's relevant since it doesn't cover generic parameter defaults.
- Smaug123 4y ago
  First hit for "Typescript equals in generic" is https://stackoverflow.com/questions/56843790/typescript-generic-type-with-equal-operator-means 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 4y ago
    Whilst that's good, the TS documents should document this. Google searching and stackoverflow is not a valid replacement for actual documentation, IMO.
u8 4y ago
Golang has https://pkg.go.dev https://pkg.go.dev. Rust has https://docs.rs 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 4y ago
  More importantly, golang has https://go.dev/ref/spec 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).
rendaw 4y ago
> 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 4y ago
  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 4y ago
    It could also be about refocusing within the Typescript project.
eitland 4y ago
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 4y ago
  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 4y ago
    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.

benced 4y ago

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 4y ago
I think you intended this as a reply to someone else. Or at least, it sounds like you're agreeing with me.

0xfffafaCrash 4y ago

https://www.typescriptlang.org/docs/handbook/release-notes/overview.html#generic-parameter-defaults https://www.typescriptlang.org/docs/handbook/release-notes/o...