[SubuSS]

Great article. Perhaps because I suck at grammar, I didn't even notice the language issues. Interesting that HN is getting bogged down analyzing grammar rather than the actual content. Were the mistakes so bad that they detracted you away from the message? FWIW I was able to comprehend it just fine.

One interesting issue I see is with specific documentation rather than 'self-documenting code': Considering docs don't compile, I have seen (in my 13 years ;) that docs tend to drift apart from the actual code and become more of a PITA than the code itself. At least once I have caught myself down a wrong path because I trusted the docs.

I don't have anything against docs though - write a bunch myself: I am very circumspect against trusting it completely though.

[andrewflnr]

Yes, they really do detract from the message. They're a jarring distraction, like a skip or buzz in a piece of music. And sometimes even when you think you've comprehended it fine, you and author are thinking about different things because you silently filled in a gap with the wrong idea (can't say for sure if there were cases like that in TFA)