Hacker News Reader

Comment by adrusi | Hacker News Reader

Mentioned as an afterthought at the end: IDE support for typescript, the best part about using the language.

Not mentioned: type annotations serve as a form of documentation that gets statically verified. The verification strategy has some cracks, and there's a (fairly small) chance that the documentation will end up misleading. But API documentation for javascript projects generally sucks, and typescript helps to fill a lot of the common gaps.

View on HN

i'm tired of devs that claim that TS and GraphQL are "self-documenting" and don't need to write any documentation. it doesn't fill in the common gaps, it's just an excuse to not have to think about or talk to users.

Do you think this claim is specific to TS/GraphQL? I've heard it from devs well before either existed.

GraphQL libraries often have built in documentation abilities that make it trivial to document, extract, and make pretty api docs fairly trivially. It’s still like pulling teeth to get developers to use the functionality at all.

That said, the appropriate reaction is to laugh louder the longer they make the claim.

In my experience it helps devs move the documentation up one level. By that I mean they don't just document the mechanics and type signature of the function, but instead document what the function is used for and why it exists.

You can already write decent docs in plain JS, but I've found that having the types already documented by the compiler helps devs move up that level of thinking automatically.

I'm the author and the claims that Graphql and typescript replace documentation is madness

...good thing that there's pretty much no one making them, then.

There's plenty of people saying that it effectively augments documentation, and provides a form of it that's quite useful.

TBF, Typescript's VScode's integration is about the best thing the language has got going for it.

It's very likely what's driving adoption right now.

Reply on news.ycombinator.com