Improve JavaScript/node/deno docs and user guide

[mhkeller]

Ported from here pola-rs/polars#21676

Description

I came to polars from Kyle Kelley's blog post about integrating Deno and Jupyter, which specifically mentions polars as a tool to use with this setup. However, I found the docs for new javascript/deno/node users hard to follow. I'll break down a few general issues I ran into as a new user. Hopefully, these observations could help identify targets to improve upon in an effort to help adoption among JavaScript developers.

Note: I'll use the term JavaScript generally here but consider it as a placeholder for runtimes like nodejs and deno.

1. The User Guide does not include JavaScript examples

The nodejs-plars page has a link to a User Guide, but that page only shows examples in Python and Rust:

NodeJS docs

Linked User Guide missing JavaScript example

It would be great if the User Guide also included JavaScript in its tutorials.

2. The nodejs-polars docs don't list intuitive functions and methods from a user's perspective.

The first thing I looked for was information on Polars DataFrames. I clicked DataFrame from the list on the left and it took me to this page, which seems to describe some more internal part of the polars API than a user-facing method. I expected to see something more like a guide that had some examples showing how a user would create a dataframe as well as a list of all of the methods I could do to that dataframe once it was created.

I think the page I'm looking for is this one, which I found by clicking pl under "Namespaces" on that page and then DataFrame under "Interfaces" on that page. This jargon is hard to follow, though.

From this page, it was still hard to find the information I wanted. For instance, it includes 406 lines of TypeScript before listing the methods available on pl.DataFrame in human language.

I'm still a bit confused by how many of them work. For example, I see that minus is a method:

I understand how to subtract one number from another, but what does it mean to subtract something from an entire DataFrame? This could be an opportunity to discuss how these operations work architecturally, when it would work and when it wouldn't, such as with a DataFrame of mixed-string and numeric types.

In general, these docs seem like they were auto-generated from the source code and while they may be "correct" in that sense, they aren't really human navigable, especially for users who aren't coming from a computer science or programming languages background.

For example, the docs for UnderscoreJS list each method with both type definitions, examples and human language. They link to the source so developers who want more detail can dig deeper. I'm not saying you need to follow this exact format but rather as an example of including information at various levels of detail.

3. Docs could benefit from examples

After I discovered that browsing methods on the pl object was more what I was looking for, I started reading about the readCSV. Here's how it describes its API:

Many users aren't used to reading type annotations, though. And for those that are, it's still useful to have a simple example, similar to what is on the Python and Rust pages, showing how to use this method.

const df = readCSV('/path/to/file.csv', {/* Include some common options here */});

Thanks for all of your work in building this library. I could see it being very helpful to the JavaScript community – especially inside of Jupyter notebooks now that Deno support is there.

Link

https://pola-rs.github.io/nodejs-polars/index.html#node

[Bidek56]

@mhkeller Thanks for your feedback.

1. The main polars repo is kind of separate from nodejs-polars repo b/c the focus is on Python.
2. nodejs-polars docs are auto-generated using typedoc and contain similar content as the Rust docs.
3. Feel free to contribute to improve the library.

[mhkeller]

Re: 1. My point was that the NodeJS docs link to a User Guide that only has Python / Rust examples. Organizationally, if you can't change that repo, perhaps creating a NodeJS-focused user guide in a repo that you do control would be a practical alternative.
Re: 2. It was definitely my intuition that these were auto-generated. My suggestion was to create something more approachable for new users. Perhaps typedoc isn't the right solution at the moment.
Re: 3. I'd love to contribute but unfortunately the lack of docs is a blocker for me in being able to understand the library and how to use it. If that changes, I'd love to use a JavaScript implementation of polars. I think it's a great idea and would help bridge the gap between people with JavaScript skills and data science workflows, as discussed here.

If the team doesn't have the bandwidth for these changes, there's a great community at Write the Docs that may have suggestions. They're much more expert than I am in documenting projects like this.

But since polars already has a User Guide, a lot of the heavy lifting has already been done. Perhaps just forking that repo into one you control and replacing the Python/Rust examples with Node ones would be the biggest reward for the smallest amount of effort.

[roll]

I would love to see more readable documentation 👍 Currenlty, I'm working on a project on top of nodejs-polars and, honestly, I just use Github code as a documentation because raw typedoc is obviously not fully useable

[ellis]

I had to abandon my attempt to use nodejs-polars due to the immaturity of the documentation, and due to some functions missing in nodejs-polars that are available in the main libraries (I don't remember which ones). Sorry that I'm not able to offer anything more constructive than that I'm rooting for this work out well for typescript going forward. Will keep an eye on it.