Google’s Documentation Style Guide – helping the writer in the developer

Google have published a style guide for their developers.

It’s a nice guide for all writers of non-fiction.

Some cute things:

On semicolons (I never know when to use) not much help (https://developers.google.com/style/semicolons)

Where to use semicolons is often a matter of judgment. Use them judiciously.

In the resources section the style guide refers to Apple’s and Microsoft’s style guides. (https://developers.google.com/style/resources)

Other companies’ style guides, such as the Apple Style Guide or the Microsoft Manual of Style.

Anthropomorphisms, which I like especially in documentation (makes them read like a novel, if done well), however not recommended by Google (https://developers.google.com/style/anthropomorphism):

Examples

Not recommended: A Delimiter object tells the splitter where a string should be broken.

Recommended: A Delimiter object specifies where to split a string.

Just one I did not understand (https://developers.google.com/style/headings):

Things to avoid in headings

Don’t use the following in headings:

Enjoyable.

Should you learn how to code?

Everyone in IT should know the basics of programming. (Also you should have installed some Linux distribution on your laptop. Even if its your laptop, it increases your understanding of the complexities of managing a platform.)

Program something

Program a crappy little program, you will understand more about the challenges of the programmer.

Derek Sivers wrote a nice article about why you should learn programming. https://sivers.org/prog
For him learning to code means self reliance and basic understanding are the main reasons.

Also experience the joy of building you own computer. I helped my son when he built his gaming computer. I learned at least as much as he did.

What language to start with

Derek recommends to start with HTML and CSS. Well, yes, agree of if you are interested in programming web sites. But HTML is such an ugly programming language. It’s like staring programming with BASIC. Before you know you think GOTO is a great flexible feature. While it actually is kitsch. I would rather start with Python, php or Java.

Build something useful in a very short time. Make it ugly. It doesn’t matter. Improve it step by step. Or start something new.

I like exploring programming languages.

 

I recently played with php. Built a small website showing photo’s from google images using random keywords.
Using MAMP.

Then played with python, programming an interface between Kindle and Evernote. Used Pydev.

Did some Javascript and node-RED.

A lot of Rexx programming. 

And Erlang.  That’s a hard one if you are not familiar with functional programming languages.

I learned a ton. I am always amazed what you can learn FOR FREE on the Internet.

Programming: a profession

Programming, a profession not a monkey task

A few years ago an IT manager said to me: for this programming job, I should be able to hire any monkey from the street.

I told him such an attitude would very quickly ruin his application, if not his entire business.

For an organisation that relies on software so heavily, allowing unmaintainable code to enter your applications is like accepting a loan your will never be able to pay off. You are building up an insurmountable technical debt. You can only hope you have some superb programmers around when the bugs hit the fan.

Programming profession

But for us programmers the problem is also about professionalism.

Coding is a profession. Good programming is a skill.

Some organisations want to have code done for 5$ per hour. Or so. Less than you would pay for a plumber. You would trust a plumber for that rate, why leave a programming job to someone for that rate? You are simply not serious about the problem at hand if you hire like that.

Democratization – the amateur and the pro

There is a tendency to underestimate the importance of skill.
Programming is democratized. That is good. Coding is not something mythical either. Amateurs can do it. Do it well. And enjoy it.

But for the problem in my organisation I need a pro.

Photographing is democratized. But for my wedding photos or for my business brochure I hire a professional photographer. Because he has a number of things extra, which I would summarize a craftsmanship and experience.

If you want stuff done you want good craftsmanship. A specialist you can talk to.

And by the way, ideally they should be at your desk and you at their’s. This is where outsourcing often goes off the track. Too little interaction.

Go pro

Cheap programming may work for throw-away apps. But not for high quality solutions that need to work be maintained for a couple of years or more. That stuff is built for the future. For maintainability.

By an expert.

7 augustus – toer #2

De volgende attractie van de toer is een bamboebrug over een rijstveld. De brug, een toeristische trekpleister, is eigenlijk een stalen skelet met bamboe aangekleed.  Er zijn nu een paar mensen op de brug door het veld. In het seizoen moet het hier enorm druk zijn.

We eten bij een restaurantje langs de weg bij de brug, en vervolgen de toer naar de waterval. Deze ligt een paar honderd meter van de weg af, de jungle in. Een smal pad leidt door een kloof naar de waterval. Een klein meertje aan de voet van de waterval. We badderen wat en nemen elkaar op de foto.

De land-split is een heel apart seismisch / geologisch (?) verschijnsel. Een jaar of twintig geleden zag een boer hier opeens in zijn landje op de berghelling enorme scheuren van wel 20-30 meter diep ontstaan. Dat maakt het land onbruikbaar voor landbouw en de boer besloot het fenomeen open te stellen voor publiek. Een paar jaar later trokken er nog meer scheuren in zijn land. De attractie wordt op een ludieke manier gefinancierd. Bij de ingang krijgen de bezoekers allerlei lekkernijen aangeboden. Lokale specialiteiten, drankjes en hapjes. Je kan deze ook kopen, maar dat hoeft niet, zegt men er bij. Allemaal heel gracieus en niet opdringerig. En de man die de boel leidt spreekt enorm goed engels. Het enige dat ze van je vragen je te overwegen een donatie te doen, van hoeveel mag je zelf weten. Dat laat je maar afhangen van hie je e.e.a. hebt ervaren. We drinken sap van de Hibiscus (bloem (?), eten tamarinde, gefrituurde bananenchips, zoete aardappel. We koepn een fles van het Hibiscusdrankje, dat waarschijnlijk straks lang niet zo goed meer smaakt.

De Pai Canyon staat als laatste op het programma van de rondleiding. De Canyon is een hele steile rotspartij van waar af je een heel mooi uitzicht over het dal van Pai hebt. Het is hier goed zweten, zo op het warmst van de dag. Japanners en Chinezen halen halsbrekende toeren uit op hun slippertje langs de hellingen. Heel mooi, uniek uitzicht over het dal rond Pai.

Op de terugweg bespreken we bij de chauffeur voor de volgende dag een bezoek aan de grotten van Lod.

7 augustus -Toer hot spring, land split, waterval, chinees dorp, Pai Canyon (1)

We worden vroeg opgehaald bij onze appartementen in Pai door onze chauffeur. Een kleine, gedrongen vent/jongen met een petje achterstevoren op zijn hoofd en een grote zonnebril op zijn neus. Hij komt met een Toyota Fortuner. Een enorme 4×4 die in Nederland alleen bereden wordt door PC Hooft bezoekers en hoort zit er een strakke blondine op de bijrijdersstoel. De chauffeur blijkt een heel aardige vent. Hij houdt van punkrock. Gedurende de hele reis zijn we verzekerd van stevige muziek, van U2 tot SoD.

We rijden eerst richting Mae Hong Son, richting de grens met Myanmar. De omgeving is schitterend. Road to Hana in Maui, maar dan zonder de zee. Onderweg passeren we controleposten van het leger. Volgens de chauffeur wordt er gecontroleerd op illegale immigranten uit Myanmar op zoek naar werk in Thailand.

De weg naar de hotspring is heel steil en bovendien na de regen van de afgelopen dagen erg modderig. We rijden een auto achterop die de helling niet op komt. De auto glijdt steeds weer naar beneden. We merken nu dat die Fortuner hier erg van pas komt. We rijden een heel eind in de lage giering (of juist de hoge) waar deze auto voor het extreme klimwerk is uitgerust. De hotspring is een plek in midden in het bos waar een restaurantje en een paar primitieve omkleedhokjes zijn gebouwd.

We springen in de warme vijver. Er dobberen al een paar toeristen in rond. Het water is schat ik zo’n 35 graden. We poedelen een tijdje en maken wat foto’s.

De anderhalf uur die onze gids hiervoor had ingepland gaan we niet volmaken. We stappen weer in en rijden langzaam terug over de gladde hellingen.

De volgende stop is het Chinese dorp. Op een heuvel in het landschap ligt een soort kasteel dat wellicht aan de Chinese muur moet doen denken, met er omheen wat gebouwtjes met winkeltjes en andere gebouwtjes. Je kan er wat dingen doen als boogschieten. Je kan je in een chinees gewaad hijsen. Maar eigenlijk is het gewoon een ordinaire tourist-trap.