Learning Curve of the API

Open

#269 opened on Feb 7, 2025 11 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 4/5
Estimated time: 3-5 days
Newbie friendliness: 35/100

Issue type: Documentation
Clarity: Mostly clear
Activity status: Stale
Tech stack: go
Domain: developer-experience, documentation

Research direction

Start by reading the existing usage patterns in the pqarrow/*_test.go files, then compare them with the README and main godoc page. Define a small set of foundational examples that explains how the API fits together for reading Parquet files, and consider where those examples should live. Done means a newcomer can follow the documented path without relying on test files.

Written by the indexing model from the issue text.

Description

Don't get me wrong, this is an incredible piece of software, and the platform-specific optimizations and complexity it handles are very impressive - mad respect to everyone involved in building it.

I do, however, find myself struggling with the API's learning curve to the point that it makes me feel very dumb and frustrated every time I want to read a few parquet files.

Currently, I rely exclusively on pqarrow/*_test.go files as my primary reference to understand usage patterns, which doesn't seem like the proper place to learn. The godoc, while being comprehensive, covers so many types and subpackages that it's hard to piece together a clear picture of how everything fits together.

I suspect other people might be hitting the same wall. The gap between understanding the API documentation and actually implementing something feels unusually wide here compared to other packages in the Go ecosystem.

I thought that maybe adding some foundational examples in the README or the main godoc page could make a huge difference in helping devs get over that initial hump and make the project appear more approachable.

Dominant language: Assembly
Stars: 406
Forks: 146
Avg merge: 2d 8h
Merged PRs (30d): 93

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.