Skip to main content

Ralsina.Me — Roberto Alsina's website

Posts about programmning

Soft Skill: Writing


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?


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?


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.


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.


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!


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.


  • Spell­ing
  • Gram­mar


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.


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.

Contents © 2000-2023 Roberto Alsina