back to article 'Don't Google Google, Googling Google is wrong', says Google

If you want to write developer documentation like a Google hotshot, you'd better kill “kill”, junk “jank” and unlearn “learnings”. Those are just a few rules from the company's newly open-sourced (oops, two sins there, verbing and hyphenation) developer documentation guide. Even though any Linux user knows “kill” is a command …

Page:

  1. Anonymous Coward
    Anonymous Coward

    Real Developers write developer documentation not PhD theses.

    1. Adam 52 Silver badge

      "Real programmers" in the Ed Post sense, don't write documentation.

      Real developers, in my experience, often write barely comprehensible poorly structured documentation that does little to help anyone who has to maintain their code. It will tell you that the function LogMessage logs a message, but doesn't tell you how the code fits together, how the underlying algorithm works or what the business need was.

      Now that we're all Agile, of course, we prefer working code over documentation. Which is fine; just show me some perfectly working code.

      1. Prof. William Waterman Sherman

        I'm not a coder, but I read a lot of code to gain insight into problems I'm tasked with fixing. I've learned to identify developers by their peculiar spelling and grammar quirks. For example, "thier" in a comment line indicates Andy wrote that particular routine, while "there" when he means "they're" points to Bob. And, if the code contains proper grammar and missing joins in an SQL query, of course it's Carl!

        Bless their hearts. I love them all.

    2. Oh Homer Silver badge
      Pirate

      Don't "Google it"!

      This demand will likely be obeyed with the same rigour as Hormel's demand that we stop blocking "spam" and Adobe's demand that we stop "photoshopping" images.

      1. illiad

        Re: Don't "Google it"!

        Yes.... google, you have got to that level of fame, stop moaning about grammar, and be proud that almost no-one says 'search the internet' anymore!! If bing had been as good and inclusive, superbly effective etc, we would use that word...

        we all say 'sellotape' even though it usually a cheaper brand of adhesive tape!! same thing with Hoover, etc...

        1. Teknogrot

          Re: Don't "Google it"!

          I was working for MS via a third party when Bing was just being rolled out and scuttlebutt was that while the engine was being developed and demonstrated internally the engineers kept saying "and then I google <thing>" over and over, until some exec stopped them and said "But it's not Google". No idea how true that is, but I really hope it happened like that.

          In particular because at the time they were just literally Googling stuff and reformatting the results...

  2. Anonymous Coward
    Anonymous Coward

    Google is the king of "Jank"

    “Jank” (Wiktionary says “blocking of a software application's user interface due to slow operations or poor interface design”) should be used with care"

    Tell that to the Google team that came up with the web based Gmail login page, the Gmail remove accounts (from login page) and the tedious 35 step process to check/'opt-out' of, what are just 5 settings, in terms of setting user privacy regards Google's data slurp.

    Google is the king of "Jank".

    1. Dan 55 Silver badge

      Re: Google is the king of "Jank"

      May I nominate Google News on mobile which isn't just janky but often siezes up completely.

      1. FrankAlphaXII Silver badge

        Re: Google is the king of "Jank"

        Funny enough it does the same on a Pixel using Chrome.

        Or displays "local" news from Mountain View, when I live about a thousand miles away, which the phone surely knows.

  3. Lysenko

    +1 for killing "learnings". Next up against the wall, "learners" (pupils) and "reached out to" (contacted).

    1. tfewster Silver badge
      Thumb Up

      Contacting someone implies you were successful; "reaching out" and "pinging" can be useful in context, especially if you don't really care about the result: "Yeah, I reached out to (difficult person with a notoriously short attention span) [with a PGP encrypted linguine-long technical proposal] and s/he didn't have any objections"

      1. Lysenko

        re: Contacting someone implies you were successful;...

        "Reaching out" implies you used your arm and "pinging" implies you used an ICMP packet.

        1. psychonaut

          Re: re: Contacting someone implies you were successful;...

          "i will be doing the necessary".

          Someone in India has taught all the call centre staff this. it makes me giggle and go crazy in equal amounts.

          And yank date format....eeeurgh.

          1. ChrisElvidge

            Re: re: Contacting someone implies you were successful;...

            "i will be doing the necessary"

            I learned it as "I will be doing the needful."

            1. yoganmahew

              Re: re: Contacting someone implies you were successful;...

              Make sure you revert with the needful by [some arbitrary time] sharp!

            2. Captain DaFt

              Re: re: Contacting someone implies you were successful;...

              "i will be doing the necessary"

              I learned it as "I will be doing the needful."

              Whatever. Just don't accidentally the whole thing again, OK?

          2. Arthur the cat Silver badge

            Re: re: Contacting someone implies you were successful;...

            "i will be doing the necessary".

            Someone in India has taught all the call centre staff this. it makes me giggle and go crazy in equal amounts.

            Almost certainly standard Indian English, which is yet another variation in our great common tongue. My personal favourite IndEng word is "prepone", meaning "to bring forward in time", by analogy with "postpone".

            1. LionelB

              Re: re: Contacting someone implies you were successful;...

              My personal favourite IndEng word is "prepone", meaning "to bring forward in time", by analogy with "postpone".

              Mine is "doubt" to express a misunderstanding. As an academic I am sometimes contacted by Indian students/researchers expressing a "doubt" about some aspect of my published work. The first few times this happened I thought they were being a bit cheeky, until I twigged that they were just seeking clarification.

          3. Registre

            Re: re: Contacting someone implies you were successful;...

            ""i will be doing the necessary".

            Someone in India has taught all the call centre staff this. it makes me giggle and go crazy in equal amounts."

            Does this sound weird to Anglos ? It's the literal translation of a standard French expression.

          4. fidodogbreath Silver badge

            Re: re: Contacting someone implies you were successful;...

            "i will be doing the necessary".

            "Please do the needful" was my favorite variation on that.

          5. Ballast

            Re: re: Contacting someone implies you were successful;...

            I get "Do the needful", which I find charming but ultimately incorrect.

        2. Anonymous Coward
          Anonymous Coward

          Re: re: Contacting someone implies you were successful;...

          "and "pinging" implies you used an ICMP packet."

          Not necessarily. The TCP-IP context derives from the use of literal "pings" in ASDIC/SONAR in underwater warfare.Therefore it can have a similar figurative use in any attempt at contact that consists of a short question/answer exchange.

          1. DJSpuddyLizard

            Re: re: Contacting someone implies you were successful;...

            Yes, and both of these really just mean "checked to see if something was there."

            In that context, I can go around pinging customers all day, but it won't really tell me anything useful, apart from those people still exist or that they are not responding.

          2. Anonymous Coward
            Anonymous Coward

            Re: re: Contacting someone implies you were successful;...

            Yeah but the cnuts with whom I work can regularly be heard using the phrase "I'll ping you an email"...

            If I wasn't so anonymous I'd think they do it just to wind me up.

          3. the spectacularly refined chap

            Re: re: Contacting someone implies you were successful;...

            The TCP-IP context derives from the use of literal "pings" in ASDIC/SONAR in underwater warfare.

            Ping is ICMP, not TCP...

            1. Anonymous Coward
              Anonymous Coward

              Re: re: Contacting someone implies you were successful;...

              "Ping is ICMP, not TCP..."

              Have an upvote (up-vote?) for petty correction of the day!

            2. Anonymous Coward
              Anonymous Coward

              Re: re: Contacting someone implies you were successful;...

              And ICMP is part of the TCP/IP protocol stack...

              1. the spectacularly refined chap

                Re: re: Contacting someone implies you were successful;...

                No, it sits directly on top of bare IP.

                1. dom_f

                  Re: re: Contacting someone implies you were successful;...

                  So should be ICMP/IP to follow the same naming? Not that I see UDP/IP used much!

        3. ZanzibarRastapopulous

          Re: re: Contacting someone implies you were successful;...

          > "Reaching out" implies you used your arm....

          Is that the same as fisting?

        4. Andrew Punch

          Re: re: Contacting someone implies you were successful;...

          "Pinging" sounds like flicking the target in the ear

        5. Montreal Sean

          Re: re: Contacting someone implies you were successful;...

          "Reaching out" implies you used your arm and "pinging" implies you used an ICMP packet.

          I read that as using an ICBM, and thought that's quite a ping! :)

        6. trydk

          Re: Contacting someone implies you were successful;...

          Historically, I would say "pinging" implies you used a sonar, which really shows how conservative we are when it comes to language.

          Language is evolving and has, ever since its first use, always been evolving. It is, in my opinion, acceptable, as long as it is augmenting the language (like "tweet" to mean "send a short message on Twitter" and not just the chirping of a bird) while not changing the original meaning (as to a certain extent has happened to "literally", which originally meant "using the original meaning of a phrase" ("The flour literally exploded from the spark") to now meaning "figuratively" or perhaps "virtually" ("She literally exploded with rage").

      2. yoganmahew

        I think the old airline abbreviations UTC and LMTCB work over "reached out".

      3. AndrueC Silver badge
    2. Anonymous Coward
      Anonymous Coward

      "[...] "learners" (pupils) [...]"

      You can be learning something by experience without being a pupil or even a student. Possibly "novice" or "tyro" are closer.

    3. Spanners Silver badge
      Boffin

      Lets remove a few more. I suggest we get rid of such misuses as...

      Share - try "discuss" instead

      and

      Student - when they mean pre university school pupils

      Then, all you kids can get off my lawn!

    4. Anonymous Coward
      Anonymous Coward

      Can we please add

      "surfacing" to the death list. PLEASE? I throw up a little in my mouth every time I hear someone say that they "surfaced" something, or their nifty new application "surfaces" some magical data. FFS.

      1. acid andy

        Re: Can we please add

        Luckily for me, I don't think I've heard that one yet. What does it mean, "derived" or "generated" or "discovered"?

        1. Anonymous Coward
          Anonymous Coward

          Re: Can we please add

          Expose(s)

    5. plrndl

      Next up against the wall

      ...and gifting.

  4. 27escape

    September 13, 2017

    Is still American date format, just not MM-DD-YYYY and is still an abomination

    1. wolfetone Silver badge

      Re: September 13, 2017

      Damn straight. Everyone should adopt the UNIX timestamp and be done with it.

      1. aks Bronze badge

        Re: September 13, 2017

        i think you mean iso date format rather than unix.

        if you're going to put the day after the month then the year should go before them both.

        while we're on the subject, iso time format should also be preferred. am and pm are anathema in my book.

        date-time should always be in gmt, obviously. (i don't refer to it as utc as i'm from greenwich). zulu rules, ok.

        1. Zippy's Sausage Factory

          Re: September 13, 2017

          But UTC was adopted on the grounds that the UK might decide to implement double summer time, and move the winter time an hour forward, or adopt BST all year round. At that point, GMT would then be different from UTC.

          Currently only Morocco uses UTC, as they don't bother with the summer/winter time stuff.

          And before you ask, I live in WET, which is currently the same as GMT...

          1. PNGuinn
            WTF?

            Re: GMT

            No, GMT would remain GMT whatever the Grubbymint decides watches in Greenwich should be set to. It's a standard, see. Like badgers' feet.

            C'mon, standards soviet. We need a standard location for standard time to give a standard offset from Imaginary Time. AND a set of real elReg time units.

            That'd end all the confusion for good. Ideas on the back of a perfectly smooth badger please ....

        2. katrinab Silver badge

          Re: September 13, 2017

          GMT is not the same as UTC, there can be a difference of up to 2 seconds between the two.

          GMT is based on the actual position of the sun at noon on the Greenwich meridian. UTC is taken from an atomic clock that can be adjusted up to twice a year on 30th June and 31st December by one second backwards or forwards to bring it closer to GMT.

        3. PNGuinn
          Coat

          Re: am and pm

          In these pc days shirly we need more than 2 options?

          I mean, this IS the 21st century after all. Just having 2 options is so last century.

          am, ateabreak, pteabreak, ap, pp, ash*t, psh*t, aamsh*t, alunch, plunch, aidon'tgiveaflyingfu*km ...

          Hmmmm my spellchecker didn't complain about ash*t.

          NURSE! I need a commode. Or a new iphone.

          >>Thanks. You don't want to know what's in the pocketses

      2. GnuTzu Bronze badge

        Re: September 13, 2017

        ISO 8601, RFC 3339: the justification solid and irrefutable, and cultural bias is just that, bias.

    2. DaLo

      Re: September 13, 2017

      True but at least it is unambiguous. It is ridiculous that it still isn't standardised to use yyyymmdd with or without hyphens or colons. The amount of times I've either been struggling to find a log entry only to realise the date format hasn't been localised or I have to scroll down out of the single digit dates to see what format they are using [fragmentation, consider re-writing]

      Similar for times when using a cloudy service.[don't use nouns as adjectives] Are they local to the cloud, are they local are they UTC?[Rhetorical, avoid]

Page:

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Biting the hand that feeds IT © 1998–2019