Hacker News new | ask | show | jobs
by baremetal 1484 days ago
you will include non-technical issues in your technical documentation and you will like it?
2 comments

Yep. They're attempting to strong arm people into Orwellian newspeak.

And good grief. The potential to spin an open source ASIC for free, simply to get experience is an AMAZING opportunity.

But I'll leave engineering before I submit to the arbitrary and ever changing demands of some potentate of newspeak. Doubleplusungood.

It’s more like “if you want us to pay for your project, kindly refrain from the unnecessary use of wording that is offensive, in non-technically-required ways, in your documentation.”

Is that really so bad?

Did you look at the guidelines? Their definition of offensive seems to be "someone, somewhere might completely misinterpret what you said in such a way as to take offense." In the real world, no one takes offense at the phrase "first-class functions", but in Google's world someone apparently does.
I couldn’t find a definition of offensive from Google. Many of their specific policies seem quite reasonable to me. Some are in a category that could be quite demeaning to a respectably large group of people and do so for no purpose. (See “turn a blind eye”, for example.). Some have nothing to do with offensiveness but are about clarity (e.g. “holidays” — for a lot of the world, the big long holiday season simply isn’t what Americans think of it as, and, as a programmer writing in the most widely-understood language in the world, one should realize that many of one’s readers aren’t American). Some are bizarre (e.g. Google’s alternative suggestion for “hamburger menu” literally cannot be written in an HN comment and is about as easy to read out loud as the artist formerly known as Prince’s unpronounceable name; I think Google is trying to make technical writing accessible to users of assistive technologies here, but I don’t think the resulting guideline is actually practical to follow in many contexts or achieves its goal. I don’t use assistive technologies, but, if I were unable to perceive the “hamburger” icon, I have trouble imagining that a screen reader or similar system would interpret Google’s icon-based name for it in a way that made any sense at all.

And yes, some can be baffling. I’m having trouble figuring out what first-class citizen is a reference to, if anything. Wikipedia’s article on first class citizens attributes the name to a paper by Christopher Strachey, which contains a single instance of the word “citizen” or a variant thereof:

> Thus in a sense procedures in ALGOL are second class citizens

Which is clear in context and vague out of context. I assume, with no real evidence, that this is a mildly confused reference to Ancient Greece, but I could be entirely off base. In any event, the term “first class”, to me, evokes “first class mail”, which is fascinating given the complete lack of, say, second-class mail. In the UK, “first-class” has additional meanings. I’m not sure why Google thinks that “first-class” is “socially charged”. Maybe someone from Google knows?

(I understand why “blacklist” would be seen as “socially charged”, although I wouldn’t use that term. I don’t think it was originally intended as a racist term, but there was a great essay, I think by Langston Hughes, on how this type of use of “black” can be problematic. Sadly, I can’t find that essay. I could be mis-remembering who wrote it.)

The main problem is that it's explicitly pushing a certain political agenda.
Where is it explicitly pushing a "certain political agenda"? Is there a footnote somewhere that says "these documentation requirements were sponsored by <x> for congress"? You surely mean implicit. What obligation does Google have to be apolitical anyway? To make you feel more comfortable?
It's definitely more explicit than NOT having such requirements, which would be the expected norm for technical things.

Google has a HUGE amount of power over people's lives now, arguably more than the government. It has effectively become a form of government itself, but one we didn't vote for. Do you not see a problem with that?

Google a ton of dangerous unchecked power, absolutely. But it's a documentation style guide that sets off your alarms? Get over yourself.
The alarms have been going for a long time. This is just the frog-boiling water getting a little hotter.
OK, we'll tell George Orwell to get over himself. He was the one who warned us about giving excessive amounts of power to people who want to control the language.
Free speech absolutism is also a certain political agenda. At some point, everything is political and if you don't like it, you'll need to go off grid and definitely stay offline.
> At some point, everything is political

No. Football is a-political. Thanksgiving dinner is a-political. My javascript library is a-political. My silicon design is a-political.

What's happened is an extremely small subset of people have decided to push politics where it doesn't belong. Everything must become a political weapon, because everything must serve the goal of some arbitrary progress. Merely existing without putting on badges in support of The Latest Thing(TM) is offensive -- because you have implicitly not taken a side, which explicitly means you are supporting the enemy. And if that goal requires sacrifice of thanksgiving dinner and family, than so be it.

It's done wonders to improve society's polarization problem, I tell you.

Football is apolitical? Not even close. My school had a rival school, and yelling "go [rival team]!" or even wearing the wrong color during playoffs would invite physical violence, especially after folks had a few beers. The "do we build/upgrade a stadium" question is hotly contested in every city I've lived in during such a referendum. Some people, it turns out, hate football and don't want it to be in their city. That's politics. Hell, when I grew up, even mentioning football would get you booed out of any respectable nerdspace. Thanksgiving is, depending who you ask, a celebration of genocide, try again. Are you still using JavaScript? Typescript, my friend, is the way. Does your silicon design use variable names? Politics entered the chat!

No, everything is political. If you're offended, you're welcome to not participate. Polarization sucks, yes, but pretending it doesn't exist typically means you see one side as right and the other as wrong. Not helpful.

I dunno, you seem to be conflating culture and politics. Politics implies it's about power in some kind of hierarchy, culture doesn't necessarily imply that, it just implies a state of being. Is 'being vegetarian' political to a Buddhist, for example? Does anything think Buddhists are being political when they refuse meat?

I mean, everything is political just because humans do it is a funny perspective but so general that it really loses all meaning.

No one said a word about free speech "absolutism."
That doesn't refute my point, does it? One can ride a bike without saying a word about riding bikes, after all.