maprys.net

a programmer's soft skills

03 Mar 2023 (last modified 19 Aug 2023)

Before entering 2023, I began longing to find another open-source community in which to participate. During my time as a developer at Red Hat, doing so was commonplace. Open source has solidified itself as a cornerstone of sharing and transparency that I’ve taken into many parts of my life. I miss collaborating with developers on a common goal in an open forum.

Exploring communities has reminded me of additional soft skills a competent developer needs in their toolbox – outside of programming knowledge – as they contribute. Let’s take a deeper look at soft skills I find to be important.

Be compassionate

Realize that there is a real person on the receiving end of your words and actions.

Some would say this is an unnecessary point, bordering on obvious, but I disagree. Since the introduction of internet communication in the late 20^th century, I have noticed an upward trend in impersonal communication. Regardless of reason, it has resulted in increased aggression and insults, among other things, exchanged more often.

My reason for bringing this up is not to blame or shame, but rather to serve as a reminder to myself as well as you dear reader, that there is a human being seeing the words you are writing. There is a brand new developer on the mailing list that’s never used mailing lists before. There is a human being just trying to make it through a shitty day of work hoping to get home and unwind. There is a dev-ops engineer frantically searching the chat scrollback because a fatal production error has stolen a night of sleep.

Be slow to frustration and quick to help. Have compassion in all interactions with others. Treat others in the same fashion you want to be treated. Be respectful. Take an extra second to consider, “would I act like this to a person’s face?” That’s usually a fairly good indicator. We’re all out working together to make cool stuff. Enemies only make that more difficult.

Effective text communication takes practice

[G]reat writing makes remote work better. It saves time, reduces meetings, removes extrovert bias, and invites other perspectives.
– Tim Casasola

Communication in software communities is done asynchronously through text. Knowing how to write is key. It’s not an effortless switch from those accustomed to an in-person office environment. GitLab’s company handbook (which is entirely available to the public) has an amazing write up on effective textual communication, along with other great tips. I’ll pick a couple bullet points to highlight.

Use short sentences. Aim for 15 words or less. English is not the primary language of many people. Short, concise sentences increases clarity. It helps our English-as-a-second-language friends understand us.
Avoid acronyms and jargon. Explain as if you are writing to a child. Not that your reader is dumb, but doing so provides the most context. Someone may be less familiar with the knowledge domain.
Remove adverbs. If you find an adverb in what you’ve written, delete it. Use exact information instead of generalizing. “This method’s execution time has been reduced to 200 milliseconds,” is better than it being, “insanely fast now”.

This is but a small snippet of the mountain of good information buried in GitLab’s text communication handbook. I suggest you read about low-context communication as a next step!

Email is the most powerful, lowest common denominator

There is a sea of cool platforms, code forges, wikis, and chat services out there that facilitate various kinds of collaboration between developers. Many have exciting and flashy features, but email is the one thing that we all have in common. I have grown to love the simplicity of quick emails over navigating JavaScript-bloated websites and slow code forges. I realize that it’s not everyone’s preference, but some communities only use email. The Linux kernel famously continues to use plaintext mailing lists and git send-email for submitting patches. I am here to prepare you for those email-only communities. Maybe you’ll find you like their simplicity like I have.

Use plaintext

I may be biased. I recently started using the Aerc email client for interacting with my Google Mail accounts. I delete so much more email than previously. It’s been wonderful. Email lets you interact with developers in a way that is most comfortable for all parties. To some that may be console-based software like Mutt or Aerc. Others may prefer Thunderbird or a web client. Regardless of preference, with plaintext you are ensuring that your messages are as accessible as possible.

In short, HTML emails are a security nightmare, are mostly used for advertising to you and tracking you, are less accessible for many users, and don’t offer anything especially great for it.

Top-posting

When replying to an email, the client usually includes a quoted bit of text to provide context below your message. This can lead to lengthy threads housing the entire conversation history in a giant nested footer. That is called “top-posting” and is discouraged. Trim the quoted text to what is relevant, and respond directly below it.

A: Because it reverses the logical flow of conversation.
Q: Why is top posting frowned upon?

Additional email resources

Chat with purpose

Chat is everywhere in the modern world. As prevalent as email may be, sometimes it feels a little ancient compared to chat. Chat has rich text, inline images, threading, and emojis! What’s not to like?! Email and real-time chat have their respective places in software communities. Services like Discord, Slack, and IRC are common areas for communities to gather. Taking part in the conversation requires some tact and forethought on your part. Let’s dig into some of those.

Ask your question immediately and directly

When you need assistance, jump directly into your question. Pleasantries are always nice, but don’t wait for someone to respond before asking your question. This is generally referred to as “no hello,” (or less commonly as “naked pings”). Messages such as a plain, “Hi!” or “I have a question. Anyone around?” do little more than waste time. “Hi folks, I’m new. Where can I find the schedule for the monthly Q&A?” is a much better chat message because you skip the entire step of waiting to see if anyone is around. This should be applied to channels as well as private messages.

Be specific

Part of asking good questions is doing as much as you’re able before enlisting the help of others. State what you know so far from the problem you are experiencing. Read the documentation to make sure your question isn’t already answered, mentioning that you did so.

Bad:

Help! My web server isn't working! How do I make it work?

Better:

Hi, I can't get Jekyll 4.3.0 to start. I'm getting this 'Uninitialized
constant' error <link-to-stacktrace>. I read through jekyllrb.com but I
couldn't find any docs that seem directly related to my problem.

Private messages

Favor discussion in public channels. Do not private message another user without permission. Doing so is considered rude. Public discourse ensures anyone can chime in to help. Another user may very well be looking for the same assistance as you.

Additional chat / question-asking resources

While some of these resources are centered around IRC, their recommended practices apply to any chat platform.

Let’s talk code

Building software is the main reason we’re all here! It is vital that we know how to discuss it effectively. Proper code discussion, documentation, concepts, and processes affect us twofold. It 1) helps users and developers in the present, and it 2) helps users and developers in the future. Let’s look at some ways to write textual information alongside our already amazing software.

Commit messages

Commit messages are the first comments presented to a developer when viewing your codebase. It’s funny to write “Fixed more bugs” or “Some changes” as your commit message for the 3^rd time, but these messages will do little else in the future other than cause frustration. Consider using the Conventional Commits system when writing commit messages. The Conventional Commits spec is a guideline for increased descriptiveness in your commits.

Here are some examples to give you an idea:

A new feature that includes a breaking change

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other
config files

A bug fix. Extra paragraphs of detail are always welcome

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss incoming
responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are obsolete
now.

Reviewed-by: Z
Refs: #123

chore: refactor Media class to increase readability

In addition to descriptive messages, Conventional Commits make it easy to generate changelogs.

Code review

Just as we explored explicit commit messages above, we can (and should) comment explicitly when reviewing code. The Conventional Comments spec provides an outline for doing so. Similar to commits, it provides a framework for describing a type of comment and decorators for severity. Though it’s not spelled out in the spec, it encourages writing actionable messages. Tell the reviewee what you want to see. This is clearer than a statement such as, “that doesn’t work right.” The overall goal is to reduce conversation churn and undercommunication.

Your reviews turn from this:

This isn't worded correctly.

Into this:

suggestion: This isn't worded correctly.

Can we change this to match the wording of the marketing page?

Semantic Versioning

One develops software with the eventual goal of release. As software grows more complex, it is our responsibility to version software that is clear to others using it. Semantic Versioning (or “semver”) is a guideline for versioning software that is explicit in how it’s changed compared previous versions. See the summary below.

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes

At its basic level these are the entire guidelines of semver. Following these rules ensures that your users will only experience breaking changes when they’re prepared for them (i.e. - a major version change). Please see the spec if you have more detailed questions or want to know more about the nitty gritty.

Developers and users will love you for not surprising them.

Additional code resources

Closing

I hope that your takeaway from this information is not that software communities are rigid places of No Fun™. Nor is it to instill a fear of interacting incorrectly. Instead my desire is to convey that the open-source community at large has formed best practices over the years for effective communication and collaboration. As I encourage you to be compassionate, they will give you the same courtesy. You will not be banned from a community or “all open-source forever,” over a small misstep of etiquette. Do your best, apologize when necessary, then continue learning and growing.

Build cool stuff. Fix bugs. Make some friends.