undefined | Better HN

0 pointsdragonwriter12y ago0 comments

Avoiding pronouns decreases readability of documentation. And readability is more fundamental to the purpose of documentation that "findability" and "grepability".

And, given the need for explicit referents preceding uses of pronouns (other than "one"/"many", which aren't the kind of pronouns at issue here), using them properly doesn't negatively impact searching.

0 comments

3 comments · 1 top-level

thenerdfiles12y ago· 2 in thread

Readability has a subjective basis and in this case comes with a cost. Findability and grepability have clear advantages without the cost that readability incurs (the gendered pronoun debate). If you apply a pure text search engine over such documentation, relevance and discovery is enhanced. Signal-to-noise, again.

You're telling me that "it" or "they" riddled more often than otherwise does not negatively affect search results? Pronouns increase the chance irrelevant results. This is implied by your use of "properly"; which only begs the question.

dragonwriterOP12y ago

> You're telling me that "it" or "they" riddled more often than otherwise does not negatively affect search results?

Basically. More specifically, I would say that using definite pronouns improves search results.

> Pronouns increase the chance irrelevant results.

No, because there is no reason to search for definite pronouns, you search for the nouns that are the antecedents of definite pronouns (since using a definite pronoun requires using a noun as an antecedent in writing -- this can be substituted by gesture or other non-verbal cues in oral communication.) And if you use pronouns, you get less result clutter for those searches for the same reasons that you get better readability, you have less close-proximity repetition of the key nouns.

thenerdfiles12y ago

I just want to state that I think we have an interesting sub-discussion/set of theories here, even if mine is radically false. It's true or false on account of testability, in the end, I genuinely believe.

j / k navigate · click thread line to collapse