Intro

There is a some­what ar­bi­­trary sep­a­ra­­tion in tech be­tween soft and hard skil­l­s.

Hard skills are tech­ni­­cal skil­l­s. Know­ing a pro­­gram­ming lan­guage. Un­der­­s­tand­ing a pro­­to­­col. Ex­pe­ri­ence with a spe­­cif­ic piece of soft­­ware. Which is all good and nice, of course. Most of us work­ing in tech en­joy these "hard skil­l­s", or we would work on some­thing else, right?

Soft skills is ev­ery­thing else. Know­ing how to ne­­go­ti­ate your sal­lary? Soft. Be­ing good man­ag­ing your tick­­et­s? Soft. Com­­mu­ni­­ca­­tion? Pre­sen­­ta­­tion of knowl­­edge? Knowl­­edge shar­ing? Soft, soft, soft.

See more about soft skills here.

To­day's soft skil­l?

Naming Things

Which is, of course, one of the fa­mous two hard things in com­put­er sci­ence¹

There are on­ly two hard things in Com­put­er Sci­ence: cache in­val­i­da­tion and nam­ing things.

-- Phil Karl­ton

This is an un­der­rat­ed skil­l. Ad­ver­tis­ers and wiz­ards know a good name is a big deal, and once a name is ap­plied, get­ting rid of it is very dif­fi­cult, so it's a good idea to try to get it right (or at least not hor­ri­bly wrong) the first time.

Know your audience

You will see here rules. They are all meant to be bro­ken on oc­ca­sion. Which ones can be bro­ken and which ones can't?

It de­pend­s.

If it's an in­ter­nal tool in a com­pa­ny where ev­ery­one speaks en­glish, then you don't need to spend much ef­fort mak­ing sure it does­n't mean "tes­ti­cles" in ger­man (it's Ho­den, BTW)

If it's a niche open source tool then the rule against ob­scure jokes does­n't re­al­ly ap­ply be­cause there's tra­di­tion.

OTOH call­ing things by of­fen­sive names with in­tent is prob­a­bly al­ways a bad idea.

Where do you draw the line? Well, if I could give you an al­go­rithm for that it would not be a soft skil­l, would it?

Rules For Names

So, what's a good name?

It's not a common word.

Make it easy to google. Please. Make it be some­thing that's not al­ready a much larg­er thing. Do not call your big­int li­brary "Grande". No­body will be able to ask about it with­out be­ing flood­ed by links about tiny singers and large (not not the largest) cof­fees.

So, if you can't come up with a very un­com­mon word ... go to oth­er lan­guages. Go to un­usu­al lan­guages. That, plus con­tex­t, will help.

It's not a "bad word" in another language.

Yeah, that suck­s. But hey, it's al­so hard to fig­ure out in ad­vance. At least check Eng­lish Span­ish and Can­tonese ?

There is a rea­son why the Mit­subishi Pa­jero is called "Mon­tero" in span­ish-s­peak­ing coun­tries.

It's not an obscure joke.

Python is called Python be­cause of Mon­ty Python. Which means the place where you down­load­ed pack­ages was called "The Cheese Shop". And the for­mat for the pack­ages was called a wheel (as in "a wheel of cheese").

Ob­scure jokes have a ten­den­cy to en­cour­age sec­ondary, more ob­scure jokes to the point of in­co­her­ence. Try ex­plain­ing "why is this called a wheel?".

Re­cur­sive acronyms count as ob­scure jokes. Yes.

Make it memorable and descriptive.

Not "Ob­ject Adapter Li­brary"

Not "Lan­guage Ex­ten­sion Pack­age"

Yes, those names are "de­scrip­tive" in a dry, to­tal­ly un­in­for­ma­tive way, but I am go­ing to for­get them in 30 sec­onds and I just made them up right now.

So, use an ar­bi­trary, mem­o­rable name. If it works as a men­motech­nic for what the thing does, bet­ter. Good ex­am­ples:

• SQLAlche­my: mem­o­rable. It's about SQL. It sug­­gest com­­pli­­ca­­tion and prob­a­bly some su­per­­nat­u­ral in­­ter­ven­­tion will be nec­es­sary.

• Djan­­go: mem­o­rable.

• Ru­­by on Rail­s: mem­o­rable. It's about Ru­­by. Ok, so it's not about train­s, but "on rail­s" has metaphor­i­­cal mean­ing.

And yes, this rule 65% of the time col­lides with "not an ob­scure joke".

Make it short

"L­lan­fair­p­wl­l-g­wyn­gyll­gogerych­wyrn­drob-wl­l­l­lan­tysil­i­o­gogogoch En­ter­prise Edi­tion" is bad.

Don't make it too short

"C" is bad (it was good in the 70s!).

Make it clear in context

Nam­ing things is not on­ly about nam­ing soft­ware or things, it's al­so about vari­ables, class­es, and iden­ti­fiers in code in gen­er­al.

• "i" is of­ten bad
• "str­First­Name" is al­ways bad
• "data" is al­ways re­al­ly bad
• "Ob­jec­tAdapter­In­ter­face" is mak­ing my eyes bleed.

A name is not a de­scrip­tion. So, "str­First­Name" is try­ing to de­scribe "it's a string with the first name in it". What else is it go­ing to be? A boolean? Do you call your pet "dog­Fi­do"?

But a name has to be a name. If you call your dog "dog", then "data" and "i" will look good to you.

And a name is not a DNA test. You don't need to de­scribe the an­ces­try of things, just say what they are. A glass is not a Drink­ing­Wa­ter­Con­tain­er. It's a glass. ²

Name things what they are, or some­thing that lets you iden­ti­fy them. I know, rad­i­cal.

Conclusion

You did­n't ex­pect me to solve one of the hard prob­lem­s, did you? No, I won't. These are just, like I said, rules meant to be bro­ken. But you need to break them con­scious­ly.

For ex­am­ple, I am nam­ing a project of mine Co­braPy. be­cause it's an 80s-style retro thing, and in the 80s Karate Kid was cool, and in Karate Kid there's Co­bra Kai, and that sort of sounds like Co­braPy and Py is for Python, and Co­bras are al­so snakes.

But I named it that on pur­pose.

Intro

There is a some­what ar­bi­trary sep­a­ra­tion in tech be­tween soft and hard skill­s.

Hard skills are tech­ni­cal skill­s. Know­ing a pro­gram­ming lan­guage. Un­der­stand­ing a pro­to­col. Ex­pe­ri­ence with a spe­cif­ic piece of soft­ware. Which is all good and nice, of course. Most of us work­ing in tech en­joy these "hard skill­s", or we would work on some­thing else, right?

Soft skills is ev­ery­thing else. Know­ing how to ne­go­ti­ate your sal­lary? Soft. Be­ing good man­ag­ing your tick­et­s? Soft. Com­mu­ni­ca­tion? Pre­sen­ta­tion of knowl­edge? Knowl­edge shar­ing? Soft, soft, soft.

One prob­lem with this sep­a­ra­tion is that the word "hard" in Eng­lish means two things. It means the op­po­site of soft, as when we say "hard­ware" and "soft­ware", but it al­so means dif­fi­cult. There is a sub­lim­i­nal mes­sag­ing that "soft" skills are the easy part, and "hard" skills are the im­por­tant stuff.

This leads to a (in my opin­ion) dam­ag­ing pri­or­iza­tion of skill­s. You can learn a new pro­gram­ming lan­guage in a few days or week­s. You can be flu­ent in a few weeks or month­s. Spe­cial­ly if you are a quick study. Or your co­work­ers are good at knowl­edge shar­ing. Or you are of a cu­ri­ous na­ture. Which are all "soft" skill­s.

And "soft" skills are, in some cas­es, much hard­er to ac­quire. You are not go­ing to take a week off and be more em­pa­thet­ic. There is no ude­my course to not be an ass­hole.

So in this ar­ti­cle, and maybe in oth­ers in the fu­ture, I will high­light some soft skills and try to de­scribe how they can help you be bet­ter at your job.

To­day's soft skil­l?

Writing

Ama­zon im­ple­ment­ed a meet­ing prac­tice where they start by read­ing a five-­page sum­ma­ry pa­per, in si­lence. That way ev­ery­one start­ed the meet­ing in equal foot­ing, know­ing what the meet­ing is about, the meet­ing is fo­cused, and less time is wast­ed ex­plain­ing things par­tic­i­pants should know.

So, imag­ine you had to do that. Do you feel you can do it?

I owe some of the best mo­ments of my ca­reer to writ­ing not code, but just writ­ing ... some­thing. Writ­ing in a tech­ni­cal po­si­tion is not about style, al­though style does­n't re­al­ly hurt as long as it does­n't af­fect the more func­tion­al side of writ­ing.

Now, what are (in my very hum­ble opin­ion) some good fea­tures in pro­fes­sion­al writ­ing?

Clarity

The goal of writ­ing at work is to com­mu­ni­cate. If the re­cip­i­ent of your writ­ing does­n't get the ex­act thing you were try­ing to con­vey then you have failed. Yes, this lim­its some­what how you can write. If there's a choice be­tween style and clar­i­ty, then clar­i­ty should win.

Lists are clear. Bul­let points are clear. Num­bered/let­tered lists are bet­ter if the or­der is im­por­tant or if you need to re­fer to list items lat­er. In those cas­es you should al­so ex­plain why the list is there.

For ex­am­ple, this is ok:

We need to de­cide whether we will use Git­lab or Github for host­ing our code. The im­por­tant fea­tures we need from the cho­sen so­lu­tion are:

• Sup­port for pri­vate repos­i­to­ries
• Good in­te­gra­tion with our ex­ist­ing Gitea CI serv­er
• In­te­grat­ed code re­view sup­port

When in doubt make lists ... is not the worst ad­vice? At least it will keep your text easy to refac­tor. Some peo­ple just do the lists and then fill in the rest. That of­ten work­s!

Short para­graph­s.

Rea­son­ably sim­ple lan­guage.

Conciseness

Keep it as short as pos­si­ble, but no short­er. As long as you are not los­ing mean­ing or clar­i­ty, short is bet­ter.

Shared

Writ­ing that you don't share is ac­tu­al­ly valu­able. I have tons of notes I take while think­ing things through. How­ev­er, shared writ­ing is bet­ter. In fac­t, it some­times makes sense to take those notes and just at­tach them to a tick­et. If you had to think 4 hours how the damned thing work­s, then there may just be val­ue there!

Relevant

It should be about the thing it's about. If you are writ­ing a doc­u­ment about a pro­jec­t, it bet­ter be about the projec­t. If you are writ­ing a doc­u­ment to sup­port an out­come of a de­ci­sion, your doc­u­ment bet­ter be:

• About the de­ci­sion
• Sup­port­ive of the out­come you want

It's tempt­ing to write about all the pos­si­ble choic­es, or wan­der in­to all the his­toric events that led to the sit­u­a­tion where the de­ci­sion needs to be made. But con­sid­er the au­di­ence. If they al­ready know those things, then is it worth it to spend their at­ten­tion bud­get in it?

Have a map

A pro­fes­sion­al doc­u­ment goes from A to B. Some peo­ple can get there just fine. Some peo­ple need google maps telling them where to turn. Just in case, get a map.

Do a very ba­sic out­line of what you want to say, such as:

• Brief de­scrip­tion of cur­rent sit­u­a­tion
• Present op­tions
• De­scribe ben­e­fits and con­cerns about op­tion A
• De­scribe ben­e­fits and con­cerns about op­tion B
• Fun­da­ment rec­om­mend­ing op­tion A over B
• De­scribe pos­si­ble ways to know if we are right or wrong
• Con­clu­sions and sum­ma­ry

And then try to fol­low it.

Basics

• Spell­ing
• Gram­mar

Extras

Yes, make it not bor­ing. Yes, you can have your own "voice". Yes, what­ev­er, but on­ly if it does­n't hurt the more im­por­tant things.

Conclusion

Im­prov­ing your writ­ing can help you fur­ther your ca­reer, com­mu­ni­cate bet­ter with cowork­er­s, avoid con­fu­sion, keep a prop­er record of de­ci­sion­s, and make your life eas­i­er in gen­er­al. Do it.