3 ms·

And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing

And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing either a few or a lot of user guides and tutorials, and directing users to either read those and try to interpret their mysteries, or expecting users to read the source code and interpret those mysteries. It makes no sense to me. The Pydantic issue tracker for example is absolutely full of people simply trying to figure out how to use the damn thing.

benrutter 3y ago
Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation. I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.
- nerdponx 3y ago
  I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
  - fuzztester 3y ago
    Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.
    - nerdponx 3y ago
      But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.
      - fuzztester 3y ago
        Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.
  - benrutter 3y ago
    I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to. I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
  - DandyDev 3y ago
    You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs
distcs 3y ago
Glad you picked on pydantic. There is no reference doc whatsoever. The expectation is that you are supposed to learn by reading examples! Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.
- palata 3y ago
  > Those days are gone! Everyone imports everything today without any discerning eye. That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.
  - pgeorgi 3y ago
    Even the good old venerable Ada language (or rather: its most visible vendor) jumped on that bandwagon with https://alire.ada.dev/ https://alire.ada.dev/ :-(

benrutter 3y ago

Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation. I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.

nerdponx 3y ago
I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
- fuzztester 3y ago
  Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.
  - nerdponx 3y ago
    But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.
    - fuzztester 3y ago
      Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.
- benrutter 3y ago
  I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to. I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
- DandyDev 3y ago
  You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs

distcs 3y ago

Glad you picked on pydantic. There is no reference doc whatsoever. The expectation is that you are supposed to learn by reading examples! Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.

palata 3y ago
> Those days are gone! Everyone imports everything today without any discerning eye. That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.
- pgeorgi 3y ago
  Even the good old venerable Ada language (or rather: its most visible vendor) jumped on that bandwagon with https://alire.ada.dev/ https://alire.ada.dev/ :-(