4 ms·

When this article first appeared, I wrote a long comment here (now deleted) about how the content Mozilla inherited from Netscape DevEdge originally straddled t

When this article first appeared, I wrote a long comment here (now deleted) about how the content Mozilla inherited from Netscape DevEdge originally straddled the split by fully embracing that there were two different mindsets the audience might be coming in with, and simply creating two different sets of docs. There were the JavaScript Guide and the JavaScript Reference, for example, and they were pretty thoroughly cross-linked. It's been years since I stopped contributing to and reading MDN, but this editorial stance seems to have disappeared, unfortunately.

ghostly_s 9y ago
Python's official docs do a good job with this approach too, I think. The Python Language Reference is relatively easy to read for a lay-man when that's necessary, and includes the formal logic of the spec in little call-out boxes -- but it's also accompanied by the Python Tutorial, which manages to cover nearly everything while making no attempt to get into every edge-case and obscure method, keeping it focused and readable. It's a great learning tool to get up to near-proficiency, and then the Reference is there for all those little "but I wonder what happens when..." questions.
- matt4077 9y ago
  I think Python is the worst-documented large language I use. For ```list``` it says: Lists implement all of the common and mutable sequence operations. Lists also provide the following additional method: ...where "common" and "mutable" are links. Meaning: the methods of lists are strewn across three different location, four if you count the constructors above this sentence.
  - anowlcalledjosh 9y ago
    Some context: the page documenting lists [0] is the same page that documents all* Python's built-in types; lists are documented in section 4.6.4, where section 4.6 is titled "Sequence Types — list, tuple, range". Many operations on a list are much the same as the methods on a tuple, so they are documented in one place – section 4.6.1 "Common Sequence Operations" – rather than duplicated in both the list and tuple documentation. Similarly, many of the methods supported by list are also supported by bytearray, so they are documented in 4.6.3 "Mutable Sequence Types" rather than duplicated. To get from the section on lists to the two sections describing the available methods involves pressing page-up twice. Hardly "strewn across three different location", and there's always help(list) if you really want a list of every supported method. *all the ones you'll use regularly, at least [0]: https://docs.python.org/3/library/stdtypes.html#lists https://docs.python.org/3/library/stdtypes.html#lists
- nl 9y ago
  Oh wow, I disagree with this quite strongly. I find they lack useful examples, and it's ridiculously hard to find even the list of methods.
  - Doxin 9y ago
    What even does "the list of methods" mean? Do you mean the builtins? Those are at the docs for built in functions.[1] Or do you mean the list of all functions? Because that doesn't exist for the very good reason that it doesn't make sense to have a list like that for python. There's the module index[2] though which lists every available module, linking to their docs which list all the available functions in those modules. Having a single list of all functions in python makes very little sense for the simple reason that you'd not be able to find what you're looking for in that list so you might as well just use the search in the first place. Side note: if there's a specific function you'd like to get the documentation for you can get that easily from the interactive python prompt with the "help" function: >>> help(zip) And I fail to see the "missing examples". While it's true that most modules don't contain examples for every single function they usually contain a few examples for the overarching concept. So which part exactly of the python docs is bad? IMO they are, by far, the best docs any programming language has. [1] https://docs.python.org/3/library/functions.html https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html
    - nl 9y ago
      Yes, I realize I can use help. Does it being available in one place mean that it shouldn't be available in others? If I'm in an IDE I don't always have the command prompt in front of me, and that should be fine! So here's the standard library page for Python lists: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range https://docs.python.org/3/library/stdtypes.html#sequence-typ... As a new python programmer, how am I supposed to know that the comprehensive API docs are actually in the tutorial? https://docs.python.org/3.1/tutorial/datastructures.html https://docs.python.org/3.1/tutorial/datastructures.html Compare that to Javadocs (something Java got right!): https://docs.oracle.com/javase/8/docs/api/java/util/List.html https://docs.oracle.com/javase/8/docs/api/java/util/List.htm..., and .NET is similar. Ruby is also ok in this regard: https://ruby-doc.org/core-2.2.0/Array.html https://ruby-doc.org/core-2.2.0/Array.html (Javascript is a mess of course!)

ghostly_s 9y ago

Python's official docs do a good job with this approach too, I think. The Python Language Reference is relatively easy to read for a lay-man when that's necessary, and includes the formal logic of the spec in little call-out boxes -- but it's also accompanied by the Python Tutorial, which manages to cover nearly everything while making no attempt to get into every edge-case and obscure method, keeping it focused and readable. It's a great learning tool to get up to near-proficiency, and then the Reference is there for all those little "but I wonder what happens when..." questions.

matt4077 9y ago
I think Python is the worst-documented large language I use. For ```list``` it says: Lists implement all of the common and mutable sequence operations. Lists also provide the following additional method: ...where "common" and "mutable" are links. Meaning: the methods of lists are strewn across three different location, four if you count the constructors above this sentence.
- anowlcalledjosh 9y ago
  Some context: the page documenting lists [0] is the same page that documents all* Python's built-in types; lists are documented in section 4.6.4, where section 4.6 is titled "Sequence Types — list, tuple, range". Many operations on a list are much the same as the methods on a tuple, so they are documented in one place – section 4.6.1 "Common Sequence Operations" – rather than duplicated in both the list and tuple documentation. Similarly, many of the methods supported by list are also supported by bytearray, so they are documented in 4.6.3 "Mutable Sequence Types" rather than duplicated. To get from the section on lists to the two sections describing the available methods involves pressing page-up twice. Hardly "strewn across three different location", and there's always help(list) if you really want a list of every supported method. *all the ones you'll use regularly, at least [0]: https://docs.python.org/3/library/stdtypes.html#lists https://docs.python.org/3/library/stdtypes.html#lists
nl 9y ago
Oh wow, I disagree with this quite strongly. I find they lack useful examples, and it's ridiculously hard to find even the list of methods.
- Doxin 9y ago
  What even does "the list of methods" mean? Do you mean the builtins? Those are at the docs for built in functions.[1] Or do you mean the list of all functions? Because that doesn't exist for the very good reason that it doesn't make sense to have a list like that for python. There's the module index[2] though which lists every available module, linking to their docs which list all the available functions in those modules. Having a single list of all functions in python makes very little sense for the simple reason that you'd not be able to find what you're looking for in that list so you might as well just use the search in the first place. Side note: if there's a specific function you'd like to get the documentation for you can get that easily from the interactive python prompt with the "help" function: >>> help(zip) And I fail to see the "missing examples". While it's true that most modules don't contain examples for every single function they usually contain a few examples for the overarching concept. So which part exactly of the python docs is bad? IMO they are, by far, the best docs any programming language has. [1] https://docs.python.org/3/library/functions.html https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html
  - nl 9y ago
    Yes, I realize I can use help. Does it being available in one place mean that it shouldn't be available in others? If I'm in an IDE I don't always have the command prompt in front of me, and that should be fine! So here's the standard library page for Python lists: https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range https://docs.python.org/3/library/stdtypes.html#sequence-typ... As a new python programmer, how am I supposed to know that the comprehensive API docs are actually in the tutorial? https://docs.python.org/3.1/tutorial/datastructures.html https://docs.python.org/3.1/tutorial/datastructures.html Compare that to Javadocs (something Java got right!): https://docs.oracle.com/javase/8/docs/api/java/util/List.html https://docs.oracle.com/javase/8/docs/api/java/util/List.htm..., and .NET is similar. Ruby is also ok in this regard: https://ruby-doc.org/core-2.2.0/Array.html https://ruby-doc.org/core-2.2.0/Array.html (Javascript is a mess of course!)