Philipp Albrecht

Philipp Albrecht

Backend nerd telling other people to add tests

Can you elaborate, please?

3 minute read

TLDR: Contributing to Servo taught me how communication is an invaluable skill that should be nurtured and cultivated as much as writing clean, idiomatic code.

Almost one year ago I started to consistently work on Servo issues in my spare time and besides learning Rust and having tons of fun, it taught me to become a better developer in so many ways. Mostly because the Servo team members are truly amazing people, who openly share their passion for technicalities with newcomers and make the overall contributing experience very pleasant, intriguing and potentially addictive. But as much as I love to talk about how amazing Mozillians are (dare ask my wife about it), in this post I’m focusing on the most valuable thing I’ve learned by contributing.

Providing meaningful context

My initial motivation of contributing to Servo was to learn Rust. To my surprise that is the one thing I’ve learned the least during the last year of contributing (I’m quite confident reading Rust code, but writing idiomatic Rust is a whole different story). What I actually learned to be the most valuable lesson is the importance of communicating context to fellow developers.

As a newcomer I usually have many questions when tackling a new issue and I don’t want the reponse to my supposedly well crafted question be along the lines of:

Can you elaborate, please?

That’s no fun. Especially if you have to wait at least 8 hours for a response, because the person lives on the other side of the globe in a different time zone.

So, putting the problem with all its context into such precise words, that the reader will fully understand the issue without having to ask any more questions, should be the goal here. The more context you provide and the more precise that context describes the problem at hand, the more approachable it will be for someone else to respond and the greater the chances of the response solving your problem first try. Playing comment ping-pong with an 8 hour distance is not very efficient and, as mentioned before, no fun.

What is meaningful context?

The answer to this question is obvious: it depends.
It depends on the problem you’re trying to solve and on the reader’s skills and technical background.

What? You wouldn’t consider this answer helpful?

Alright, let me soothe the excruciating pain of unfulfilled expectations with a list of my self-imposed guidelines for communicating context:

  • Provide all involved resources: this may include links to relevant code, specifications documents, and examples in the form of code snippets.

  • Explain your unsuccessful attempts: what have you tried to solve the problem? What were the results? Did you rule out any options? If so, what were the reasons for ruling them out?

  • Put effort into correct spelling, grammar, punctuation and layout: these things matter! Nobody likes to read a giant single block of text. Make people enjoy reading your request and they will more likely put effort into their response.

  • Never assume the reader knows what your talking about: just because the reader is the team lead with 20+ years of experience, doesn’t mean he/she can read minds and knows what you’re struggling with.

  • Be grateful: don’t take it for granted that people are taking the time to answer your questions. They’re not getting paid to walk the extra mile for you, so show them appreciation for helping you out!

These are the things I keep in mind, when providing context (e.g. writing a comment or filing an issue on Github). This list is non-exhaustive. You’ll find a ton of valuable information related to the subject online. Here a few links to get you started:

Conclusion

I think it’s a great challenge to provide context that is just on point and easy to read. It translates so well into other areas, because it’s more of a communcation skill rather than a technical one, and therefore absolutely worth cultivating. It saves both the asker and the answerer a lot of time and leaves people happy instead of frustrated and unmotivated.

:wq

Updated: