Soft Skill: Writing
There is a somewhat arbitrary separation in tech between soft and hard skills.
Hard skills are technical skills. Knowing a programming language. Understanding a protocol. Experience with a specific piece of software. Which is all good and nice, of course. Most of us working in tech enjoy these "hard skills", or we would work on something else, right?
Soft skills is everything else. Knowing how to negotiate your sallary? Soft. Being good managing your tickets? Soft. Communication? Presentation of knowledge? Knowledge sharing? Soft, soft, soft.
One problem with this separation is that the word "hard" in English means two things. It means the opposite of soft, as when we say "hardware" and "software", but it also means difficult. There is a subliminal messaging that "soft" skills are the easy part, and "hard" skills are the important stuff.
This leads to a (in my opinion) damaging priorization of skills. You can learn a new programming language in a few days or weeks. You can be fluent in a few weeks or months. Specially if you are a quick study. Or your coworkers are good at knowledge sharing. Or you are of a curious nature. Which are all "soft" skills.
And "soft" skills are, in some cases, much harder to acquire. You are not going to take a week off and be more empathetic. There is no udemy course to not be an asshole.
So in this article, and maybe in others in the future, I will highlight some soft skills and try to describe how they can help you be better at your job.
Today's soft skill?
Amazon implemented a meeting practice where they start by reading a five-page summary paper, in silence. That way everyone started the meeting in equal footing, knowing what the meeting is about, the meeting is focused, and less time is wasted explaining things participants should know.
So, imagine you had to do that. Do you feel you can do it?
I owe some of the best moments of my career to writing not code, but just writing ... something. Writing in a technical position is not about style, although style doesn't really hurt as long as it doesn't affect the more functional side of writing.
Now, what are (in my very humble opinion) some good features in professional writing?
The goal of writing at work is to communicate. If the recipient of your writing doesn't get the exact thing you were trying to convey then you have failed. Yes, this limits somewhat how you can write. If there's a choice between style and clarity, then clarity should win.
Lists are clear. Bullet points are clear. Numbered/lettered lists are better if the order is important or if you need to refer to list items later. In those cases you should also explain why the list is there.
For example, this is ok:
We need to decide whether we will use Gitlab or Github for hosting our code. The important features we need from the chosen solution are:
- Support for private repositories
- Good integration with our existing Gitea CI server
- Integrated code review support
When in doubt make lists ... is not the worst advice? At least it will keep your text easy to refactor. Some people just do the lists and then fill in the rest. That often works!
Reasonably simple language.
Keep it as short as possible, but no shorter. As long as you are not losing meaning or clarity, short is better.
Writing that you don't share is actually valuable. I have tons of notes I take while thinking things through. However, shared writing is better. In fact, it sometimes makes sense to take those notes and just attach them to a ticket. If you had to think 4 hours how the damned thing works, then there may just be value there!
It should be about the thing it's about. If you are writing a document about a project, it better be about the project. If you are writing a document to support an outcome of a decision, your document better be:
- About the decision
- Supportive of the outcome you want
It's tempting to write about all the possible choices, or wander into all the historic events that led to the situation where the decision needs to be made. But consider the audience. If they already know those things, then is it worth it to spend their attention budget in it?
Have a map
A professional document goes from A to B. Some people can get there just fine. Some people need google maps telling them where to turn. Just in case, get a map.
Do a very basic outline of what you want to say, such as:
- Brief description of current situation
- Present options
- Describe benefits and concerns about option A
- Describe benefits and concerns about option B
- Fundament recommending option A over B
- Describe possible ways to know if we are right or wrong
- Conclusions and summary
And then try to follow it.
Yes, make it not boring. Yes, you can have your own "voice". Yes, whatever, but only if it doesn't hurt the more important things.
Improving your writing can help you further your career, communicate better with coworkers, avoid confusion, keep a proper record of decisions, and make your life easier in general. Do it.