Hacker News Reader

Comment by IgorPartola | Hacker News Reader

Guess: a lot of developers conflate Python documentation with documentation for various Python libraries as found on PyPI. Documentation for these libraries varies from great to "I'll just read the source."

I've actually found myself doing quite a bit of code reading for Django. As much as the team tries, there is quite a bit of undocumented magic that can really trip you up if you are not doing exactly the right things. For example, don't create a source-tree/project/__init__.py file (sibling to your settings.py) that does any type of imports.

View on HN

I'm going to guess that any dev worthy of the name can discern between a library and core python. I'll allow that I may hold python devs to a standard higher than is realistic (I'm new to using python in my daily work, and not well-versed in how the python community rolls.)

As noted elsewhere, there can be a lot of Ctrl/Command-f'ing to find what you want. That, and sometimes I just want an example of what I have to think is the most common case for a function. Instead I often get examples of esoteric cases that I'll likely never do. I mean, it's nice that those capabilities are there and that they're documented, but I just want to (made-up example) search for a simple ASCII substring, not a UTF-8 substring in a Unicode string using a regex all fourteen optional parameters.

That said, I wouldn't go so far as to say that the docs are bad, but they could certainly be better.

Agreed on the whole, but if we can agree that for ever good developer there are 10x beginners, we can infer that it's the 10x beginners' searches that influence the Google autocomplete.

I can most certainly agree because, sadly, it's a POV that hadn't crossed my mind despite being the basis of the article.

That's something I love about JavaScript. Most libraries have great documentation, and the source is usually easy to understand. With C#, I feel the opposite is the case. Documentation either doesn't exist or is very basic, reading the source is quite hard because its common to put code in as much files as possible.

Really? I think a lot of people find the opposite to be true about Javascript, in terms of source. Javascript allows for some fun magic, but that pretty quickly cuts into readability/debugability. Look at Bluebird -- works great, but not just a "I'll jump right in here and understand it" sort of module.

You're definitely right about the C# docs, though. I always feel totally lost looking through those, especially since I'm not much of a C# dev to begin with.

Reply on news.ycombinator.com