5 ms·

It's odd but when I have to write something with Python, its documentation really is terrible. There's not even index of functions in particular module, I have

It's odd but when I have to write something with Python, its documentation really is terrible. There's not even index of functions in particular module, I have to open it, then find that function with ctrl+f. E.g. https://docs.python.org/3/library/os.html https://docs.python.org/3/library/os.html Compare to golang: https://pkg.go.dev/os https://pkg.go.dev/os it provides list of all functions in particular module which I can glance over quickly and find what needed. That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need. And I never had issues with JavaScript thanks to wonderful MDN.

OJFord 5y ago
Python's the main language I've used professionally (i.e. used most by a long shot) and I agree. I think it's just a newer style, newer languages and frameworks seem to have a more structured/hierarchical/indexed style like that IME.
- FooBarWidget 5y ago
  Newer? If you look at Javadocs, they're highly structured, at least as much as — and arguably more so than — Go docs. I think it has got more to do with culture and tradition. Each language seems to have its own documentation culture. Python seems to favor docs in which structure is interleaved with prose. I find Go docs to be pretty hard to make sense of. Often times they don't explain very well how to use a package. And browsing around different aspects of a library carries a feeling of obscurity. Ultimately, I think documentation should be split up into multiple categories, ala https://documentation.divio.com/ https://documentation.divio.com/
  - Izkata 5y ago
    Python is about 4 years older than Java (based on "initial release" listed on Wikipedia), so the pattern still fits between those two languages.
  - chaxor 5y ago
    Java is a newer language though isn't it? The 90's wasn't so long ago... right guys? ... guys? :(
noisy_boy 5y ago
The best example of being lost in docs is Python's re (regex). Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. If I have a specific requirement or want the gory details, I can always scroll down.
- bmn__ 5y ago
  > Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. This is called a synopsis, and lack of one is the single biggest mistake that documentation authors make. When I look across the landscape of programming languages, I see them rarely. Perl documentation always has a synopsis because it's a big cultural expectation, and it almost always useful to get the user started, or to jog the memory. Man pages have it, too, but they tend to cram too much useless information instead of restricting to common cases and patterns.
  - bccdee 5y ago
    The issue is that there are conflicting use cases — "I want to refresh myself on how `re` works" and "tell me what order the arguments for `re.match` go in". I think the second use case is most frequent, so an index and some basic examples should go first, but after that a more in-depth synopsis can be very helpful.
    - blakesley 5y ago
      Isn't it more natural that the summary comes first, before the details?
      - bccdee 5y ago
        I don't think most visits to documentation involve reading the summary; they're either looking for a specific detail (which they can find via the index) or for a common snippet that can be expressed in an example. If I'm using `re` and I check the documentation 20 times over the course of the week, I'll probably read the summary on my first visit, and then on each of the 19 subsequent visits I'll be looking for granular function details or patterns that I can copy. I think it makes sense to put the most frequently-used stuff at the top. The summary will probably be denser and harder to skim than the examples anyway. I suppose it really depends though. What you want is to get a bit of everything before the break, so that the user can see a couple intro sentences, a few examples, the index (ideally in a sidebar), and the beginning of the overview before they even have to scroll.
ascar 5y ago
I tend to agree. Python's style of documentation was always hard to parse for me. In comparison I really liked the Ruby core documentation. Short description with common use case examples followed by a structured list of all implemented functions and a sidebar linking to all relevant interfaces/superclasses. E.g. the Hash class document : https://ruby-doc.org/core-3.0.3/Hash.html https://ruby-doc.org/core-3.0.3/Hash.html
wongarsu 5y ago
Python documentation isn't as nice to read as that of go or rust, and at places a bit hand-wavy. But compared to javascript/typescript it's well structured and thorough. GP just wasn't setting the bar all that high.
- stevula 5y ago
  Many consider MDN the gold standard when it comes to language documentation and they cover all the JS browser API. I find it much preferable to Python’s docs. If you’re talking about TS or Node docs, I’ll agree they’re not on the same level as MDN.
mrsuprawsm 5y ago
I like to use Dash https://kapeli.com/dash https://kapeli.com/dash, which makes browsing the standard library for Python really fast and smooth. One could argue that you shouldn't need a separate app for documentation, and you might be right, but it is a great experience.
kqr 5y ago
I think this is a cultural difference. Python documentation tends to be of the cookbook style, where you have long instructions surrounding specific examples. This works well for some people. Other language communities (the typical example for me is Haskell) aim more for reference style documentation, emphasising lists of the possible operations and then trusting people to sequence those operations as they wish themselves. That's the type of documentation I like. I have yet to find a language community that does a good job of both of these styles of documentation at the same time. C# is sometimes in the right direction, but not always.
- asdff 5y ago
  R does a good job imo. Look at the vignette for print in R vs the help page in python. You get your reference style list of possible arguments, you get info on usage as well as additional examples, you even get a See Also section with further reading, and the whole thing has a citation you can reference. The entire language is documented thoroughly like this.
  - kqr 5y ago
    R is a good one indeed. I still haven't figured out how to get a good overview of the functions available in R grouped in some sensible way, but at least once I know which function I want it's often very well documented.
    - pvaldes 5y ago
      > I still haven't figured out how to get a good overview of the functions available in R Is not obvious, but can be done from the inside with plain R. You could also want to type install.packages('ctv') and take a look to Cran task views
- Gunax 5y ago
  I barely know it, but my brief experience with clojure has inspired me on how documentation should work. Ex. https://clojuredocs.org/clojure.core/reduce https://clojuredocs.org/clojure.core/reduce The pattern is definition -> description -> community examples. If I ever invent a language I am copying this format.
dr_zoidberg 5y ago
> That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need. I've been programming in python for almost 15 years and I don't know all the functions/classes/attributes of any module in the standard library probably. What I do know is that if I'm on a vanilla python shell I can type `help(module)` and I'll get that list in the shell directly, and even `help(module.function)` will give me enough context most of the time that I won't need to go online either. However, as my daily shell, I use IPython, on which I have smart autocomplete that inspects the modules for me by just typing `module.`, hit tab and BAM! All the things inside the module pop up before me to explore. Something looks about what I need? I add a ? at the end an press enter, so `module.function?` will show me the docstring, nicely formatted with the signture (the same thing the built-in `help()` does). So the online docs, for python, rest on an entirely different level. But sure, coming from other languages it may be weird not having what you're used to. It's part of the languages culture.
mjburgess 5y ago
dir(module) help(module.fn)
asdff 5y ago
I agree that python documentation can be clunky especially in comparison with other languages. When I learned python I had experience in bash and R. Man pages and R vignettes have certainly spoiled me. R has usage, details, several examples, even a see also section for further reading. The equivalent python help page for a command like print is a little bit over six lines in comparison.
slaymaker1907 5y ago
My biggest grip with Python documentation is that it often leaves flags and options underdocumented.

OJFord 5y ago

Python's the main language I've used professionally (i.e. used most by a long shot) and I agree. I think it's just a newer style, newer languages and frameworks seem to have a more structured/hierarchical/indexed style like that IME.

FooBarWidget 5y ago
Newer? If you look at Javadocs, they're highly structured, at least as much as — and arguably more so than — Go docs. I think it has got more to do with culture and tradition. Each language seems to have its own documentation culture. Python seems to favor docs in which structure is interleaved with prose. I find Go docs to be pretty hard to make sense of. Often times they don't explain very well how to use a package. And browsing around different aspects of a library carries a feeling of obscurity. Ultimately, I think documentation should be split up into multiple categories, ala https://documentation.divio.com/ https://documentation.divio.com/
- Izkata 5y ago
  Python is about 4 years older than Java (based on "initial release" listed on Wikipedia), so the pattern still fits between those two languages.
- chaxor 5y ago
  Java is a newer language though isn't it? The 90's wasn't so long ago... right guys? ... guys? :(

noisy_boy 5y ago

The best example of being lost in docs is Python's re (regex). Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. If I have a specific requirement or want the gory details, I can always scroll down.

bmn__ 5y ago
> Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. This is called a synopsis, and lack of one is the single biggest mistake that documentation authors make. When I look across the landscape of programming languages, I see them rarely. Perl documentation always has a synopsis because it's a big cultural expectation, and it almost always useful to get the user started, or to jog the memory. Man pages have it, too, but they tend to cram too much useless information instead of restricting to common cases and patterns.
- bccdee 5y ago
  The issue is that there are conflicting use cases — "I want to refresh myself on how `re` works" and "tell me what order the arguments for `re.match` go in". I think the second use case is most frequent, so an index and some basic examples should go first, but after that a more in-depth synopsis can be very helpful.
  - blakesley 5y ago
    Isn't it more natural that the summary comes first, before the details?
    - bccdee 5y ago
      I don't think most visits to documentation involve reading the summary; they're either looking for a specific detail (which they can find via the index) or for a common snippet that can be expressed in an example. If I'm using `re` and I check the documentation 20 times over the course of the week, I'll probably read the summary on my first visit, and then on each of the 19 subsequent visits I'll be looking for granular function details or patterns that I can copy. I think it makes sense to put the most frequently-used stuff at the top. The summary will probably be denser and harder to skim than the examples anyway. I suppose it really depends though. What you want is to get a bit of everything before the break, so that the user can see a couple intro sentences, a few examples, the index (ideally in a sidebar), and the beginning of the overview before they even have to scroll.

ascar 5y ago

I tend to agree. Python's style of documentation was always hard to parse for me. In comparison I really liked the Ruby core documentation. Short description with common use case examples followed by a structured list of all implemented functions and a sidebar linking to all relevant interfaces/superclasses. E.g. the Hash class document : https://ruby-doc.org/core-3.0.3/Hash.html https://ruby-doc.org/core-3.0.3/Hash.html

wongarsu 5y ago

Python documentation isn't as nice to read as that of go or rust, and at places a bit hand-wavy. But compared to javascript/typescript it's well structured and thorough. GP just wasn't setting the bar all that high.

stevula 5y ago
Many consider MDN the gold standard when it comes to language documentation and they cover all the JS browser API. I find it much preferable to Python’s docs. If you’re talking about TS or Node docs, I’ll agree they’re not on the same level as MDN.

mrsuprawsm 5y ago

I like to use Dash https://kapeli.com/dash https://kapeli.com/dash, which makes browsing the standard library for Python really fast and smooth. One could argue that you shouldn't need a separate app for documentation, and you might be right, but it is a great experience.

kqr 5y ago

I think this is a cultural difference. Python documentation tends to be of the cookbook style, where you have long instructions surrounding specific examples. This works well for some people. Other language communities (the typical example for me is Haskell) aim more for reference style documentation, emphasising lists of the possible operations and then trusting people to sequence those operations as they wish themselves. That's the type of documentation I like. I have yet to find a language community that does a good job of both of these styles of documentation at the same time. C# is sometimes in the right direction, but not always.

asdff 5y ago
R does a good job imo. Look at the vignette for print in R vs the help page in python. You get your reference style list of possible arguments, you get info on usage as well as additional examples, you even get a See Also section with further reading, and the whole thing has a citation you can reference. The entire language is documented thoroughly like this.
- kqr 5y ago
  R is a good one indeed. I still haven't figured out how to get a good overview of the functions available in R grouped in some sensible way, but at least once I know which function I want it's often very well documented.
  - pvaldes 5y ago
    > I still haven't figured out how to get a good overview of the functions available in R Is not obvious, but can be done from the inside with plain R. You could also want to type install.packages('ctv') and take a look to Cran task views
Gunax 5y ago
I barely know it, but my brief experience with clojure has inspired me on how documentation should work. Ex. https://clojuredocs.org/clojure.core/reduce https://clojuredocs.org/clojure.core/reduce The pattern is definition -> description -> community examples. If I ever invent a language I am copying this format.

dr_zoidberg 5y ago

> That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need. I've been programming in python for almost 15 years and I don't know all the functions/classes/attributes of any module in the standard library probably. What I do know is that if I'm on a vanilla python shell I can type `help(module)` and I'll get that list in the shell directly, and even `help(module.function)` will give me enough context most of the time that I won't need to go online either. However, as my daily shell, I use IPython, on which I have smart autocomplete that inspects the modules for me by just typing `module.`, hit tab and BAM! All the things inside the module pop up before me to explore. Something looks about what I need? I add a ? at the end an press enter, so `module.function?` will show me the docstring, nicely formatted with the signture (the same thing the built-in `help()` does). So the online docs, for python, rest on an entirely different level. But sure, coming from other languages it may be weird not having what you're used to. It's part of the languages culture.

mjburgess 5y ago

dir(module) help(module.fn)

asdff 5y ago

I agree that python documentation can be clunky especially in comparison with other languages. When I learned python I had experience in bash and R. Man pages and R vignettes have certainly spoiled me. R has usage, details, several examples, even a see also section for further reading. The equivalent python help page for a command like print is a little bit over six lines in comparison.

slaymaker1907 5y ago

My biggest grip with Python documentation is that it often leaves flags and options underdocumented.