Remodel (or remove) our parameter tables

[avivkeller]

As shown in the image above, the parameter tables can be really quite hard to read under various circumstances, and we should make them more readable.

[avivkeller]

(For Reference, Vercel does the following [which would tie in well with #530, which I'm working on writing based on d.ts files)

[AugustinMauroy]

Somthing like Vercel would be nice !

[canerakdas]

I did a quick test/sample, but there are still a few parts that could be improved. I’ll share the design idea here once it’s finished. I’m open to different ideas or suggestions as well 🙌

[avivkeller]

I really like that

[AugustinMauroy]

@canerakdas is it possible to have a pr to discuss about tha ?

[ovflowd]

I did a quick test/sample, but there are still a few parts that could be improved. I’ll share the design idea here once it’s finished. I’m open to different ideas or suggestions as well 🙌

I feel something is missing here, I think there needs to be an outer border as there's on Vercel's one. I also think instead of writing "Optional", just make it ?:,

[canerakdas]

@canerakdas is it possible to have a pr to discuss about tha ?

Before opening the PR, I’m planning to prepare and share the design in Figma. Creating the PR directly would probably be easier, but I thought adding it to the design system in Figma would be more sustainable in the long run 🐢

[canerakdas]

I’ve created the sample design, it would be great if you could review it and share your feedback 🙌
cc @nodejs/nodejs-website @nodejs/web-infra

https://www.figma.com/design/a10cjjw3MzvRQMPT9FP3xz/Node.js?node-id=6369-1450&t=4ztiUqT8HbzukHHz-0

[ovflowd]

The design is great, but not sure the border would be that visible on light mode, could be one of those things that is like codeboxes, always dark mode.

• We should call the section "Arguments"
• Regarding overloads, it'a a tiny bit confusing, on the design, is the "source", "destination", [...] ordered arguments? Or is "streams?:" the argument? I think in the current notion is a bit confusing what is an argument, what is an overload, and if the "Returns" for each of these arguments is just for the "Function" variation?
• The actual return type isn't a "Property" so shouldn't be together with properties? What if there are multiple return types? To which return type would be for which variation of the fn?

[canerakdas]

The design is great, but not sure the border would be that visible on light mode, could be one of those things that is like codeboxes, always dark mode.

I tried to match the border colors used in light mode so they stay consistent with the rest of the page. We could also use the dark theme in this area even in light mode, but that might be a bit much (I’m not entirely sure)

Regarding overloads, it'a a tiny bit confusing, on the design, is the "source", "destination", [...] ordered arguments? Or is "streams?:" the argument? I think in the current notion is a bit confusing what is an argument, what is an overload, and if the "Returns" for each of these arguments is just for the "Function" variation?

Beyond the design itself, IMO these sections are generally confusing in the documentation. Instead of an overloaded, unordered notation, updating the documentation in the following way could make it much clearer;

### `stream.pipeline(streams[, options])`

* `streams` {Stream\[]|Iterable\[]|AsyncIterable\[]|Function\[]}
* `options` {Object} Pipeline options
  * `signal` {AbortSignal}
  * `end` {boolean} End the destination stream when the source stream ends.
    Transform streams are always ended, even if this value is `false`.
    **Default:** `true`.
* Returns: {Promise} Fulfills when the pipeline is complete.

### `stream.pipeline(source[, ...transforms], destination[, options])`

* `source` {Stream|Iterable|AsyncIterable|Function}
  * Returns: {Promise|AsyncIterable}
* `...transforms` {Stream|Function}
  * `source` {AsyncIterable}
  * Returns: {Promise|AsyncIterable}
* `destination` {Stream|Function}
  * `source` {AsyncIterable}
  * Returns: {Promise|AsyncIterable}
* `options` {Object} Pipeline options
  * `signal` {AbortSignal}
  * `end` {boolean} End the destination stream when the source stream ends.
    Transform streams are always ended, even if this value is `false`.
    **Default:** `true`.
* Returns: {Promise} Fulfills when the pipeline is complete.

The actual return type isn't a "Property" so shouldn't be together with properties?

To avoid this in the design, I used Open Sans instead of a IBM Plex Mono font and paired it with an return icon. I’ll take another look at how to better distinguish the return value from the other properties 🤔

What if there are multiple return types? To which return type would be for which variation of the fn?

If we convert it to the example above, I think this issue would be resolved as well. Independently of doc-kit and not just for this specific example, we could also review each page more broadly and evaluate what we can do to make the documentation more readable(doc-kit compatible) overall.

[ovflowd]

Can you update the designs with the suggestions for test?

[canerakdas]

Can you update the designs with the suggestions for test?

Updated according to comments 🤩 WDYT?

https://www.figma.com/design/a10cjjw3MzvRQMPT9FP3xz/Node.js?node-id=6382-1517&t=uUicfHrjQ7Jjn8N5-0

[ovflowd]

Can you update the designs with the suggestions for test?

Updated according to comments 🤩 WDYT?

https://www.figma.com/design/a10cjjw3MzvRQMPT9FP3xz/Node.js?node-id=6382-1517&t=uUicfHrjQ7Jjn8N5-0

This looks really good, SGTM.