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.

Introducción

Hay una se­pa­ra­ción me­dia­na­men­te ar­bi­tra­ria en el am­bien­te "de tec­no­lo­gía" en­tre ski­lls "so­ft" y "har­d".

Los hard ski­lls son ca­pa­ci­da­des téc­ni­ca­s. Co­no­cer un len­gua­je de pro­gra­ma­ció­n. En­ten­der un pro­to­co­lo. Ex­pe­rien­cia con un so­ftwa­re es­pe­cí­fi­co. To­do bien con eso, por su­pues­to. La ma­yo­ría de los que tra­ba­ja­mos en tec­no­lo­gía es por­que nos gus­tan o nos in­te­re­san esos "hard ski­ll­s", o tra­ba­ja­ría­mos de otra co­sa ¿no?

Las ha­bi­li­da­des "blan­da­s" son to­do lo de­má­s. ¿S­aber ne­go­ciar tu sa­la­rio? So­ft. ¿Ser pro­li­jo ma­ne­jan­do tus ti­cke­ts? So­ft. ¿Co­mu­ni­ca­ció­n? ¿Pre­sen­ta­ció­n? ¿Com­par­tir co­no­ci­mien­to? So­ft, so­ft, so­ft.

Un pro­ble­ma con es­ta se­pa­ra­ción es que "har­d" en in­glés sig­ni­fi­ca dos co­sas. Sig­ni­fi­ca lo opues­to de so­ft, co­mo cuan­do de­ci­mos "har­dwa­re" y "so­ftwa­re", pe­ro tam­bién sig­ni­fi­ca "di­fí­ci­l". Hay un men­sa­je su­bli­mi­nal de que las ha­bi­li­da­des "so­ft" son la par­te fá­cil y que las hard ski­lls son la par­te im­por­tan­te.

Es­to lle­va a una (en mi opi­nió­n) per­ni­cio­sa es­ca­la de va­lo­res. Se pue­de apren­der un len­gua­je de pro­gra­ma­ción en unos días o se­ma­na­s. Po­dés do­mi­nar­lo en se­ma­nas o me­s­es, es­pe­cial­men­te si apren­dés rá­pi­do, o si tus com­pa­ñe­ros son bue­nos trans­fi­rien­do co­no­ci­mien­to, o si sos cu­rio­so por na­tu­ra­le­za ... y to­do eso son "so­ft ski­ll­s".

En cam­bio esas ha­bi­li­da­des "blan­da­s" son en mu­chos ca­sos muy di­fí­ci­les de ad­qui­ri­r. No te po­dés to­mar una se­ma­na y apren­der em­pa­tía. No hay un cur­so en ude­my pa­ra no ser fo­rro.

En es­te ar­tícu­lo, y tal vez en otros en el fu­tu­ro, voy a in­ten­tar re­sal­tar al­gu­nos so­ft ski­lls y tra­tar de des­cri­bir co­mo te pue­den ayu­dar en tu tra­ba­jo.

¿El de ho­y?

Escribir

Ha­ce un tiem­po Ama­zon im­ple­men­tó una me­to­do­lo­gía de reu­nio­nes en las que em­pie­zan sen­ta­do­s, en si­len­cio, le­yen­do un re­su­men de cin­co pá­gi­na­s. De esa for­ma to­dos em­pie­zan la reu­nión con el te­ma fres­co, sa­bien­do lo ne­ce­sa­rio, en­fo­ca­do­s, y no se pier­de el tiem­po ex­pli­can­do co­sas que los reu­ni­dos ya de­be­rían sa­be­r.

Ima­gi­ná­te que tu­vie­ras que pre­sen­tar así. ¿Po­dría­s?

Le de­bo al­gu­nos de los me­jo­res mo­men­tos de mi ca­rre­ra a es­cri­bi­r, pe­ro no a es­cri­bir có­di­go. A es­cri­bir "o­tras co­sas". Es­cri­bir en una po­si­ción téc­ni­ca no es una cues­tión de es­ti­lo, aun­que el es­ti­lo no es­tá mal mien­tras no afec­te la par­te fun­cio­nal de lo que se es­cri­be.

¿En­ton­ce­s, qué son (en mi muy hu­mil­de opi­nió­n) al­gu­nas co­sas co­pa­das cuan­do uno es­cri­be en un am­bien­te pro­fe­sio­na­l?

Claridad

El ob­je­ti­vo de es­cri­bir en el tra­ba­jo es co­mu­ni­ca­r. Si el des­ti­na­ta­rio de tu es­cri­to no re­ci­be exac­ta­men­te la mis­ma co­sa que que­rías trans­mi­tir fa­llas­te. Sí, es­to li­mi­ta un po­co el có­mo uno pue­de es­cri­bi­r. Si hay que ele­gir en­tre es­ti­lo y cla­ri­da­d, que ga­ne la cla­ri­da­d.

Las lis­tas son cla­ra­s. Los íte­ms son cla­ro­s. Las lis­tas nu­me­ra­das o con le­tras son aún me­jo­res si el or­den es im­por­tan­te o si des­pués ne­ce­si­tás ha­cer re­fe­ren­cia a un ítem. En to­dos los ca­sos de­bés ex­pli­car el mo­ti­vo de la lis­ta.

Por ejem­plo, es­to es­tá bien.

Ne­ce­si­ta­mos de­ci­dir si va­mos a usar Gi­tlab o Gi­thub pa­ra hos­tear el pro­yec­to. Las co­sas im­por­tan­tes que ne­ce­si­ta­mos en la so­lu­ción ele­gi­da so­n:

• So­por­te de re­po­si­to­rios pri­va­dos
• Bue­na in­te­gra­ción con nues­tro ser­vi­dor gi­tea de CI
• So­por­te in­te­gra­do pa­ra co­de re­view

Cuan­do ten­gas du­das ha­cé una lis­ta ... no es el peor con­se­jo. Al me­nos ha­ce que tu tex­to sea fá­cil de re­fac­to­rea­r. Al­gu­na gen­te ha­ce lis­tas y des­pués lle­na lo que va en el me­dio. ¡Fun­cio­na!

Pá­rra­fos cor­to­s.

Len­gua­je sim­ple.

Conciso

Lo más cor­to po­si­ble, pe­ro no más cor­to. Mien­tras no pier­das sig­ni­fi­ca­do o cla­ri­da­d, más cor­to es me­jo­r.

Compartido

Hay un va­lor en có­di­go que no se com­par­te. Ten­go pi­las de no­tas que to­mo mien­tras pien­so las co­sas. Sin em­bar­go, los es­cri­tos que se com­par­ten tie­nen más va­lo­r. De he­cho, a ve­ces tie­ne sen­ti­do to­mar esas no­tas y ad­jun­tar­las a un ti­cke­t. Si tu­ve que pen­sar cua­tro ho­ras co­mo fun­cio­na esa mal­di­ta co­sa, en­ton­ces ca­paz que hay va­lor en esas no­ta­s.

Relevante

De­be ser so­bre un te­ma, y no so­bre otra co­sa. Si es­tás es­cri­bien­do un do­cu­men­to re­fe­ren­te a un pro­yec­to, me­jor que sea so­bre ese pro­yec­to. Si es­tás es­cri­bien­do al­go pa­ra apo­yar una de­ci­sión es­pe­cí­fi­ca, tu do­cu­men­to de­be:

• Ser so­bre la de­ci­sión
• Ex­pli­car por qué hay que ha­cer lo que vos que­rés

Es ten­ta­dor es­cri­bir so­bre to­das las op­cio­nes po­si­ble­s, o ir­se de pa­seo por to­dos los even­tos his­tó­ri­cos que lle­va­ron a la si­tua­ción en la que es­tán aho­ra te­nien­do que to­mar la de­ci­sión pe­ro ... con­si­de­rá el pú­bli­co. ¿Si ya sa­ben esas co­sas, va­le la pe­na gas­tar su aten­ción en eso?

Tené un mapa

Un do­cu­men­to pro­fe­sio­nal va de A a B. Al­gu­nos pue­den lle­gar ahí por su cuen­ta. Al­gu­nos ne­ce­si­tan que google maps les di­ga en que es­qui­na se do­bla. Por las du­da­s, ha­cé­te un ma­pa.

Un pun­tea­do su­per bá­si­co de lo que que­rés de­ci­r, al­go co­mo:

• Bre­ve des­crip­ción de la si­tua­ción ac­tual
• Pre­sen­tar op­cio­nes
• Des­cri­bir pros y contras de op­ción A
• Des­cri­bir pros y contras de op­ción B
• Fun­da­men­tar ele­gir A y no B
• Des­cri­bir co­mo sa­ber si A es­tá fun­cio­nan­do
• Con­clu­sio­nes

Y des­pués tra­tá de se­guir­lo.

Básico

• Or­to­gra­fía
• Gra­má­ti­ca

Extras

Que no sea abu­rri­do. Sí, po­dés te­ner tu pro­pia "vo­z" cuan­do es­cri­bís. Lo que quie­ra­s, pe­ro sin arrui­nar el do­cu­men­to.

Conclusión

Me­jo­rar tu ca­pa­ci­dad de es­cri­bir te pue­de ayu­dar a pro­gre­sar en tu ca­rre­ra, co­mu­ni­car­te me­jor con com­pa­ñe­ros de tra­ba­jo, evi­tar con­fu­sio­nes, "guar­da­r" de­ci­sio­nes y ha­ce tu vi­da más fá­cil en ge­ne­ra­l.

Ha­cé­lo.