12 ms·

> Now, compare that to what happens when I search for the same in Python. I get this: > https://docs.python.org/2/library/re.html https://docs.python.org/2/lib

• jacobolus 10y ago
  Googling about Python regular expressions still returns the “Regular Expression HOWTO” near the top of the results. https://docs.python.org/3/howto/regex.html https://docs.python.org/3/howto/regex.html That’s pretty much the best succinct introductory page about regular expressions (applying to whatever language) online, and has been for 15+ years. After finishing that page, a beginning python programmer should be ready for the library reference and/or a more serious book. (No idea why the author here thinks that examples from 2008 are such a terrible thing. Nothing has changed about Python regular expressions in ages.) Overall, the Python docs are amazing. Not perfect by a long shot, but miles ahead of PHP or C++. Pretty much the best programming language documentation I’ve ever used (but I admit there are many programming languages I’ve never tried). Perhaps that’s partly down to the language itself making a lot more sense than many alternatives. The docs don’t have to do as much work to paper over brokenness. His take on the community also bears no resemblance to my experience. People on python mailing lists, IRC, local meetups, Pycon, etc. have unfailingly been friendly and welcoming and willing to bend over backwards to help newbies.
  • thr0waway1239 10y ago
    I remember first learning about NLTK, not knowing the first thing about Python, or anything at all about natural language processing. And I could just "get it". My lack of Python knowledge did not get in the way because it was like reading pseudocode. The language is so beautifully designed for the majority of the cases where you do any kind of algorithmic/math work. In fact, it may have been too beautifully designed. :-) From what I can see from comment threads [1], most people seem to want to use NLTK even if there are a lot of complaints about how it is too slow for production, and how there are much better alternatives for NLP when it comes to performance. I think people are attracted to it because of its simplicity. [1] https://news.ycombinator.com/item?id=7658977 https://news.ycombinator.com/item?id=7658977
• int_19h 10y ago
  Regarding the docs layout and "having to scroll down to see which function", I also don't quite get it. From my perspective, it's a very nice trait of Python docs compared to PHP docs, that the former actually explain how to use the various parts of the API together, before giving descriptions for every specific API. It's simply a much better way to digest it and learn to use it without making a mess (speaking of which and PHP...).
  • snovv_crash 10y ago
    Coming from statically typed languages, I've really struggled with the Python docs, because they aren't really clear with what is returned from a lot of functions, and which arguments are allowed. I end up finding an example where it is being used, then deducing from what they do with the result what was actually returned. Contrast this with the ugly-but-functional JavaDocs, which can be auto-generated, and easily shows all return types and arguments for every publicly exposed function and member variable. I understand why this can't be done automatically in Python, but at least they could put the time in to make it clear in their standard libraries.
    • vbernat 10y ago
      Python also uses autogeneration for most of the documentation, but the documentation itself is not fully autogenerated. You write your documentation and you say to Sphinx: put the generated documentation for this module here. IMO, this is something positive. You can decide the structure of your documentation and include only the most relevant references. For example, this part of the documentation for the re module is autogenerated from code: https://docs.python.org/2/library/re.html#module-contents https://docs.python.org/2/library/re.html#module-contents
      • snovv_crash 10y ago
        Agreed, but my point is that argument and return types are badly documented, and in Python autogen doesn't help this.
• huskyr 10y ago
  Quoting myself from a blog post i wrote when i was learning Python two and a half years ago [1]: Let’s say i want to know how to do the Python equivalent of PHP’s foreach. The docs about the for statement say this: The for statement is used to iterate over the elements of a sequence (such as a string, tuple or list) or other iterable object: for_stmt ::= "for" target_list "in" expression_list ":" suite ["else" ":" suite] Right, so what does that mean? What’s ::=? What’s an ‘expression list’? The expression list is evaluated once; it should yield an iterable object. An iterator is created for the result of the expression_list. The suite is then executed once for each item provided by the iterator, in the order of ascending indices. “Ascending indices”? “Suite”? This might be clear for a CI professor, but it’s not for the mere mortals that read the docs and want to get stuff done. Things haven't gotten much better since then. [1]: https://www.haykranen.nl/2014/02/12/saying-hello-to-python-some-observations/ https://www.haykranen.nl/2014/02/12/saying-hello-to-python-s...
  • jacobolus 10y ago
    You were reading the wrong docs for a newbie. The language reference is intended for people who want a very concise and precise technical document, not an introductory explanation. If you read the very beginning, the language reference is very clear about what it is and isn’t: > This reference manual describes the syntax and “core semantics” of the language. It is terse, but attempts to be exact and complete. The semantics of non-essential built-in object types and of the built-in functions and modules are described in The Python Standard Library. For an informal introduction to the language, see The Python Tutorial. You should have been looking at the Python Tutorial instead. https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/controlflow.html https://docs.python.org/3/tutorial/datastructures.html#looping-techniques https://docs.python.org/3/tutorial/datastructures.html#loopi...
    • jawbone3 10y ago
      Another nice example of what the author complains about, a "it's your own fault" reply whenever someone complains that the official language docs are hard to understand. Personally I almost never find any use from the docs whenever they come up in a google search, its almost as bad as those expert-exchange hits that used to appear. The core issue being that pythons docs are only a language reference for the vast majority of the standard library, and the size of the stdlib bein one of pythons strengths.
• Illniyar 10y ago
  I think this is the exact type of comments that the author comes out against. You aren't putting yourself in the shoes of a beginner. Let's say I'm a beginner, and I want to just experiment with the language a bit (I've already read some tutorials or am not interested) - since I'm just trying to get the feel of the language and ecosystem, I'm not trying to get a deep understanding of the language and tools - I want to match a regex. In the C++ and PHP examples he provided, the basic example is easily found - it's basically two actions - search in google and scroll to the example. What you are suggesting takes several more steps - ctrl-f for a text that you might get wrong (you've searched for sample instead of example for instance), iterate until you get the right place, etc... And that's assuming you even realize that you should run ctrl-f, why should you? The main issue though is that if I'm a beginner I'm doing this kind of searches several times a minute - to have to stop and realize what to look for every time is extremely frustrating. I've worked with Ruby,Python, Java and Javascript - python's (and django's) documentation is extremely verbose and rarely straightforward compared to the other ones.
  • junke 10y ago
    > You aren't putting yourself in the shoes of a beginner. How do you know if I am putting myself in the shoes of a beginner or not? And what kind of beginners are we talking about? Are they comfortable with a browser? Do they already know how to program something? You can't expect a single document to be relevant for all kind of people. The reference documentation has a clear target audience, which apparently conflicts with what you expect from it. > And that's assuming you even realize that you should run ctrl-f, why should you? > (you've searched for sample instead of example for instance) Okay, so you are talking about absolute beginners, with no experience whatsoever with programming. And the C++ and PHP pages are somewhat useful for them? > I've already read some tutorials or am not interested > Let's say I'm a beginner [...] I want to match a regex. Now, you are saying that you already have experience with programming? Google "python tutorial regex" gives plenty of results, the first of them being currently "Regular Expressions HOWTO" (https://docs.python.org/2/howto/regex.html https://docs.python.org/2/howto/regex.html). Absolute beginners need a teacher, a mentor, or a step-by-step book, or a very gentle tutorial, or an online REPL. That's fine. You can't please everybody in the reference documentation.
• nnq 10y ago
  > he kind of technical documentation I love to read: precise Nothing precise about it. Method signatures don't even include a clear description of what they can f return! I have to go and fish this infos from the text blob below. Even JavaScript gives you a damn return values section for every method: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/String/match https://developer.mozilla.org/en/docs/Web/JavaScript/Referen... . I can't expect a type signature like in OCaml or Haskell (yeah, H sometimes gives you only a type signature which is even worse...), but still. The cool thing about Python is not the high quality documentation. It's that you can still be productive in it despite it being a dynamic language with such a horrible and fuzzy documentation :) Guido really did a fine language design job.
  • junke 10y ago
    The "text blob" always starts explaining precisely what kind of return value to expect under which circumstances. The return value's type can change depending on the context, and using plain text is somewhat easier to write and read than trying to come up with a dedicated notation. See findall[0], for example. The structure returned depends on whether the regexp has capturing groups or not. A specialized notation could be designed to represent that, but as far as I am concerned, the textual string is good enough. Just for fun, the return type could be expressed as: [string N] (A) | [(string M) N] : (M > 1) (B) - Case A if the regexp matches N times without overlapping and without capturing any group, or capturing a single group. - Case B if the regexp matches N times without overlapping and, for each match, captures a tuple of M groups, as strings. ... where [type size] denotes a list of size "size" satisfying the type description "type". Likewise, (type size) is a tuple of "size" elements, all of which satisfying the same type. Or you could write t1 * t2 like in other languages to define cross-products. [0] https://docs.python.org/2/library/re.html#re.findall https://docs.python.org/2/library/re.html#re.findall
    • nnq 10y ago
      Your thinking is correct and precise, but I hope you never take a job of documentation writer for any project I will ever have to work with :) My example of documenting re.findall all would be smth like this: Signature: re.findall(pattern, string, flags=0) -> [str] or [(str,)] Arguments: ... Returns: - [str] -- List of Strings matching the pattern if the pattern has no capturing groups, or only one capturing group - [(str,)] -- List of Tuples of Strings, one string for each captured group, if the pattern has more than one capturing group Examples: re.findall(r"h(\w{0,10}o)", "hello hoolo water") # -> ['ello', 'oolo'] re.findall(r"h(\w{0,10}o)", "hello hoolo water") # -> ['ello', 'oolo'] re.findall(r"(h)(\w{0,10}o)", "hello hoolo water") # -> [('h', 'ello'), ('h', 'oolo')] Details: ...put here some deatailed explanations about behavior with overlapping etc.... This is the kind of documentation that really spares me a lot of time. Your explanation may be correct but I'd have to read it 5 times and then open a REPL to do a small experiment and confirm that it means what I thought it means... (I now I don't have the right to bitch about this though, the correct thing to do would be to donate some of my time and actually improve the existing docs instead of commenting on hn...)
• kawsper 10y ago
  I am a Ruby guy, but we had a project where we built a forking socket server in Python, I was really impressed with the documentation. https://docs.python.org/2/library/socketserver.html https://docs.python.org/2/library/socketserver.html https://docs.python.org/3/library/socketserver.html https://docs.python.org/3/library/socketserver.html