Got: Examples are hard to understand

[dAnjou]

What would you like to discuss?

The examples are hard to understand and require a lot of Node/JS background.

I'm confused by the mix of async/await, streams, and promises in the examples. As someone who doesn't have too much experience in the Node/JS world and doesn't work in it regularly I find it very hard to figure out how to use Got.

Checklist

• [x] I have read the documentation.

[sindresorhus]

Can you point to something specific? We want to ensure the docs are great, but your feedback is not very actionable. Keep in mind that it's expected that you know how promises and async/await work. We don't intend to document JavaScript.

[dAnjou]

I kinda understand that, it's hard to find a balance between what you can expect from a user and what you should show in the docs/examples.

I can't really suggest ideal solutions because, like I said, I don't really know what the best practices are. I'll try anyway.

The very first example is titled "Promise" but uses the "async/await" syntax which was confusing for me at first because I only knew the "xyz().then().catch()" syntax. And I'm not sure if that's just a matter of preference but the latter one would look a bit cleaner to me, just esthetically because there's less syntax, I guess.

Then in the "Streams" example, there's even more to digest especially when looking at the tip as well which mentions errors but the example doesn't include error handling.

Another thing I noticed: it's pretty hard to navigate the docs. It took me a while to understand the big picture of Got, as in, what are the top-level methods (i.e. the "entry points") and their signatures and what are the return types and argument types and their methods. I think a ToC could help, but I'd even suggest looking into the generation of a real documentation site.

Super minor: RequestError links don't work.

By the way, I do appreciate the design of the library. Even though I don't have a super deep understanding of modern Node/JS I can see that it's very flexible, especially the context and the hooks I find very useful!

[szmarczak]

I kinda understand that, it's hard to find a balance between what you can expect from a user and what you should show in the docs/examples.

We're still waiting for GitHub to make it possible to display RunKit in readme.

The very first example is titled "Promise" but uses the "async/await" syntax which was confusing for me at first because I only knew the "xyz().then().catch()" syntax. And I'm not sure if that's just a matter of preference but the latter one would look a bit cleaner to me, just esthetically because there's less syntax, I guess.

99% of the time you're looking for async/await but don't forget that those are promises too. Avoid calling .then().catch() whenever possible. That are the very basics of JavaScript at all.

Then in the "Streams" example, there's even more to digest especially when looking at the tip as well which mentions errors but the example doesn't include error handling.

You're wrong. The moment you wrote opened the issue, it was using stream.pipeline already, which includes error handling. Anyway, streams extend EventEmitter, so to catch an error you just add an error handler and that's all (Node.js has got plenty of error examples).

I think a ToC could help, but I'd even suggest looking into the generation of a real documentation site.

See #920 I don't think our documentation is any worse than Node.js'

Super minor: RequestError links don't work.

It's kinda late, but here you go :sweat_smile: 3ed4af605ca6493c080cc8003a55c3b37988efee

By the way, I do appreciate the design of the library. Even though I don't have a super deep understanding of modern Node/JS I can see that it's very flexible, especially the context and the hooks I find very useful!

We're glad! I think that #920 would solve this issue. I'm closing this for now. If you have any other questions, don't hesitate to reply.