Node: doc: guide/topic on how to use streams

[mcollina]

From the discussion at NIEU2016 it emerged that the streams docs is not user friendly, and too focused on people that already know how to compose applications using streams. They describe the API, not how to use node streams in practice. In particular, it does not highlight the use of "streams modules": through2, from2, flush-write-stream, split2, pump, end-of-stream, duplexify, bl, etc.. and most of the things that are exposed via https://github.com/maxogden/mississippi. Moreover, it does not clarify how the API exposed to core fits in the picture, and how to build applications on streams.

The work done by @substack on the streams handbook is a great starting point: https://github.com/substack/stream-handbook.

cc @nodejs/streams @nodejs/documentation

[eljefedelrodeodeljefe]

I also had a discussion and think it is a good idea. There was this effort having guides instead of just having the API docs plus some topic, where this could have been included. We should definitely put this close to the API docs, since I think it is crucial to effectively using streams.

[alexjeffburke]

Huge agreement from me. Particularly now that streams3 can be relied upon I think some 'canonical' documentation about how to run with that version of the API for those unfamiliar would be great. If we can muster a group effort this is something I'd quite like to get involved with.

Perhaps we could start a common repo or something and work on something like this in the open? You mentioned other modules, I've long thought we have a discoverability problem of stream modules conforming to the modern APIs - what about starting a list with names and uses based on the community? Final idea for a specific guide, could we could solicit examples?

[tanujasawant]

Can I be of any use here? I am new to Open-Source and I had difficulty understanding the streams docs too.

[bitpimpin]

Hey there: @Tanuja-Sawant are you writing this doc? If not, I would like help here. I have not contributed anything to node, but under my former username, I made contributions to other projects (@oddlyzen). I'd like my first contribution with this username to be here. Cool :question:

[aqrln]

@bitpimpin given the amount of time that has passed since that comment, I'd say go ahead and do it if you want :)

[wuweiweiwu]

@aqrln @mcollina Can I pick this up? I think it'll be a good first issue :)

[mcollina]

@wuweiweiwu that'd be fantastic. We also have https://nodejs.org/en/docs/guides/backpressuring-in-streams, so you can focus more on the userland side (and also mention some of the important modules on npm).

[aqrln]

@wuweiweiwu absolutely! Keep in mind that it may be quite a chunk of work on its own, so I'd recommend to open a work-in-progress PR early and proceed gradually.

[wuweiweiwu]

@mcollina @aqrln Sounds good! Seems like a lot to read. Ill get more familiar and open a WIP PR soon :)

[eragon512]

hey guys, I'd like to take up this PR if its available