Comment by threethirtytwo
1 day ago
I couldn’t care less. It always pisses me off when a reviewer of my PR just flags the entire thing because of inconsistent capitalization. It’s the right correction and I always follow through but it’s also pedantic.
It’s technically more correct. But it’s also not a very big deal. Actually it matters more in code for search-ability but for documentation and comments? Give me a fucking break.
Isn’t being technically correct an important thing for technical documentation that aims to be technically correct?
No. Why would it be? I hate it when people come up with defense based off of linguistics. Your defense is essentially "technically correct" sounds like "technical documentation" therefore one applies to the other because of the word "technical". That's an incidence of language and NOT of reality. Let me frame if from a rational and logical perspective:
Technical documentation is not a math proof. Its purpose is to transfer a working mental model to a human reader so they can make correct decisions. A document can be locally, pedantically correct and still be globally misleading if it emphasizes edge cases, omits constraints, or frames abstractions in a way that causes readers to generalize incorrectly.
In practice, what matters is not whether every sentence can be defended in isolation, but whether the document reliably produces correct outcomes in the hands of its intended audience. A simplification that is technically incomplete but operationally accurate is often better documentation than a perfectly correct description that obscures the dominant behavior of the system.
Engineers learn this the hard way. If you have ever followed documentation that was “technically correct” yet caused you to design the wrong thing, you already know this distinction matters. Correctness is necessary to an extent (and not to an excessive extent), but it is not sufficient. The goal is truthfulness at the level of use, not just sentence level defensibility.
The fact that you hate something doesn’t make it valid.
1 reply →
I see nothing pedantic in flagging capitalisation errors, but I see loads wrong with imposing one’s sloppiness on others.
Sure you do, you see a crime where no crime happened. Read my post carefully. I imposed nothing. A standard was imposed onto me. I didn't in turn impose anything on anyone else.
People may agree with you but don't imply something was done when nothing of the sort was even attempted. I did not impose my sloppiness onto others, what happened was someone tried to impose their pedantic-ness onto me and then you falsely accused me of imposing onto others. Please don't make up shit.
Attention to detail is important for many and is often a first touch with an end user. I agree with OP, if documentation is sloppy or inconsistent (I'm not saying the doc in question is because I haven't read it) it definitely reduces the impression that it's correct or reliable.
I've skipped even trying software because of poor documentation and so the response of:
> Give me a fucking break.
...seems shallow / callous.
I highly disagree. You are judging a book by it's cover. Capitalization is no different from handwriting. Substance matters, capitalization and grammar are superficial. If meaning is captured then capitalization does not intrinsically matter.
You are correct that people judge documentation off of grammar and punctuation. But this is not a rational or logical thing people do. But I can't blame you or others, I mean after all the world believes in religion, myths and other fantasmic spiritual things with no solid evidence as backing. It's normal. I just felt HN was above that. Guess I'm wrong.
>...seems shallow / callous.
Seems that way only because you're not thinking deep enough. Think carefully whether it is rational or logical to judge the works of say Einstein because he had a grammar error or bad handwriting. The two are completely orthogonal and that is the rational perspective.
In programming, capitalization does matter. Sorry.
1 reply →
You are correct, and it will be fixed!
All this for writing Rust as rust! Wow! Tell me you have ADHD without telling me you have ADHD, just get on with the work and let others do their work. Don't flag their entire work. Linguistics is very inclusive. I took a course on it. No need to be a grammar nazi