7 ms·

you will include non-technical issues in your technical documentation and you will like it?

deleted 4y ago
[deleted]
amluto 4y ago
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?
- userbinator 4y ago
  The main problem is that it's explicitly pushing a certain political agenda.
  - deleted 4y ago
    [deleted]
  - jagger27 4y ago
    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?
    - userbinator 4y ago
      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?
      - jagger27 4y ago
        Google a ton of dangerous unchecked power, absolutely. But it's a documentation style guide that sets off your alarms? Get over yourself.
        userbinator 4y ago
        The alarms have been going for a long time. This is just the frog-boiling water getting a little hotter.
        CamperBob2 4y ago
        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.
        jagger27 4y ago
        CamperBob2 4y ago
        "Master" is a role. "Main" is an identifier. When writing documentation or doing engineering work, the distinction matters. In any event, nobody asked Google for their opinion on the subject.
  - klyrs 4y ago
    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.
    - ravenstine 4y ago
      No one said a word about free speech "absolutism."
      - klyrs 4y ago
        That doesn't refute my point, does it? One can ride a bike without saying a word about riding bikes, after all.
    - bjt2n3904 4y ago
      > 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.
      - klyrs 4y ago
        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.
- lolinder 4y ago
  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.
  - amluto 4y ago
    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.)
bjt2n3904 4y ago
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.

deleted 4y ago

[deleted]

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?

userbinator 4y ago
The main problem is that it's explicitly pushing a certain political agenda.
- deleted 4y ago
  [deleted]
- jagger27 4y ago
  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?
  - userbinator 4y ago
    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?
    - jagger27 4y ago
      Google a ton of dangerous unchecked power, absolutely. But it's a documentation style guide that sets off your alarms? Get over yourself.
      - userbinator 4y ago
        The alarms have been going for a long time. This is just the frog-boiling water getting a little hotter.
      - CamperBob2 4y ago
        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.
        jagger27 4y ago
        CamperBob2 4y ago
        "Master" is a role. "Main" is an identifier. When writing documentation or doing engineering work, the distinction matters. In any event, nobody asked Google for their opinion on the subject.
- klyrs 4y ago
  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.
  - ravenstine 4y ago
    No one said a word about free speech "absolutism."
    - klyrs 4y ago
      That doesn't refute my point, does it? One can ride a bike without saying a word about riding bikes, after all.
  - bjt2n3904 4y ago
    > 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.
    - klyrs 4y ago
      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.
lolinder 4y ago
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.
- amluto 4y ago
  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.)

bjt2n3904 4y ago

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.