5 ms·

I have never seen a worse documented library. Initially I thought that they were lazy, now I realize that it cannot be documented because it is a total mess of

I have never seen a worse documented library. Initially I thought that they were lazy, now I realize that it cannot be documented because it is a total mess of a library held together with tape. Close second is the plotly library.

__mharrison__ 4y ago
Genuinely curious what you have against the Pandas documentation. It has some of the best docstrings I've seen. (I also wrote a Pandas book or two... So there's that)
- chaps 4y ago
  Docstrings are one thing, but functionality discovery, picking up from scratch, troubleshooting, etc are... not fun, nor easy with the documentation. If you know it well already and use it a lot it's easier to forgive its documentation faults since you can waive off the problems as "that's just learning something new". But for a lot of people who use it infrequently its documentation is a frustrating mess. Simple problems turn into significant time sinks of trying to find which page of the documentation to look at. A lot of issues are made worse by shit-awful interop between libraries that claim to fully support dayaframes, but often fail in non-obvious ways... meaning back to the documentation mines. I'd argue that because there's a market for a single author to write two books about it is indicative of documentation problems.
  - __mharrison__ 4y ago
    Fair enough. I'm highly biased and my recent book is the most popular Pandas book currently, so it is evidence that folks prefer opinionated documentation. However, I always though the 10 minutes to Pandas page was decent for getting started. I picked up Polars recently and thought it was more difficult than Pandas because there wasn't any quick intro docs. What projects have great introductory docs for you? Also, I am curious to learn more about the specifics of interop libraries you are referring to. Learning a new tool is generally a challenge. I think another challenge with a lot of data tools is that non-programmers tend to be the major audience. I make my living teaching "non-programmers" how to use these tools. That said, I always teach "go to the docstrings and stay in your environment (to not break flow) if you can." The pydata docstrings are better than most, including Python (the language).
    - chaps 4y ago
      Yeah, I think for your audience, pandas makes total sense! When I first started using it, it was through an ambitiously large project with tons of gaps in data, untype-able text for 1% of rows, didn't fit in memory.. etc. So my personal experience is a bit tainted by putting myself through a hell that could have solved sooner by spending more time learning instead of bashing my keyboard with a hammer.
bobertlo 4y ago
I think the R docs are the intended reference material for pandas ;)
nerdponx 4y ago
The Pandas documentation has improved quite a bit. Last I checked, the only part of the reference docs with a big gap was the description of "extension arrays" and accessors. The user guide material absolutely needs work, and the examples in the reference docs tend to be a little contrived. But I absolutely have seen worse-documented libraries, such as Gunicorn and Pydantic.
- claytonjy 4y ago
  I'm surprised to see Pydantic in here; I've used Pandas and Pydantic both quite a lot, and have found the Pydantic docs to be quite good! Also a much smaller library with a saner API, and thus easier to document well.
333luke 4y ago
What makes the documentation so bad in your opinion? I’m not arguing but curious since I use pandas all day at my job and can’t think of any times the docs weren’t clear to me. (Plotly I have had some annoying times with!)
BeefWellington 4y ago
I've long suspected that Pandas has taken a similar stance to e-mail scammers. Where e-mail scammers inject all kinds of broken english and bad punctuation to ensure they get their targets of choice, Pandas has broken and often inaccurate documentation in order to get only the chosen ones to work with their software. However, maybe it makes more sense that it's just a mess that's hard to document.
- __mharrison__ 4y ago
  Do you have a specific example of this broken documentation?

__mharrison__ 4y ago

Genuinely curious what you have against the Pandas documentation. It has some of the best docstrings I've seen. (I also wrote a Pandas book or two... So there's that)

chaps 4y ago
Docstrings are one thing, but functionality discovery, picking up from scratch, troubleshooting, etc are... not fun, nor easy with the documentation. If you know it well already and use it a lot it's easier to forgive its documentation faults since you can waive off the problems as "that's just learning something new". But for a lot of people who use it infrequently its documentation is a frustrating mess. Simple problems turn into significant time sinks of trying to find which page of the documentation to look at. A lot of issues are made worse by shit-awful interop between libraries that claim to fully support dayaframes, but often fail in non-obvious ways... meaning back to the documentation mines. I'd argue that because there's a market for a single author to write two books about it is indicative of documentation problems.
- __mharrison__ 4y ago
  Fair enough. I'm highly biased and my recent book is the most popular Pandas book currently, so it is evidence that folks prefer opinionated documentation. However, I always though the 10 minutes to Pandas page was decent for getting started. I picked up Polars recently and thought it was more difficult than Pandas because there wasn't any quick intro docs. What projects have great introductory docs for you? Also, I am curious to learn more about the specifics of interop libraries you are referring to. Learning a new tool is generally a challenge. I think another challenge with a lot of data tools is that non-programmers tend to be the major audience. I make my living teaching "non-programmers" how to use these tools. That said, I always teach "go to the docstrings and stay in your environment (to not break flow) if you can." The pydata docstrings are better than most, including Python (the language).
  - chaps 4y ago
    Yeah, I think for your audience, pandas makes total sense! When I first started using it, it was through an ambitiously large project with tons of gaps in data, untype-able text for 1% of rows, didn't fit in memory.. etc. So my personal experience is a bit tainted by putting myself through a hell that could have solved sooner by spending more time learning instead of bashing my keyboard with a hammer.

bobertlo 4y ago

I think the R docs are the intended reference material for pandas ;)

nerdponx 4y ago

The Pandas documentation has improved quite a bit. Last I checked, the only part of the reference docs with a big gap was the description of "extension arrays" and accessors. The user guide material absolutely needs work, and the examples in the reference docs tend to be a little contrived. But I absolutely have seen worse-documented libraries, such as Gunicorn and Pydantic.

claytonjy 4y ago
I'm surprised to see Pydantic in here; I've used Pandas and Pydantic both quite a lot, and have found the Pydantic docs to be quite good! Also a much smaller library with a saner API, and thus easier to document well.

333luke 4y ago

What makes the documentation so bad in your opinion? I’m not arguing but curious since I use pandas all day at my job and can’t think of any times the docs weren’t clear to me. (Plotly I have had some annoying times with!)

BeefWellington 4y ago

I've long suspected that Pandas has taken a similar stance to e-mail scammers. Where e-mail scammers inject all kinds of broken english and bad punctuation to ensure they get their targets of choice, Pandas has broken and often inaccurate documentation in order to get only the chosen ones to work with their software. However, maybe it makes more sense that it's just a mess that's hard to document.

__mharrison__ 4y ago
Do you have a specific example of this broken documentation?