Forem: Pavithra Eswaramoorthy

Beginner's Guide to Communication in FOSS

Pavithra Eswaramoorthy — Sat, 17 Oct 2020 23:49:41 +0000

Free and Open Source software is maintained by people working remotely from around the world. Hence, effective communication is important for any project to function smoothly. Especially, asynchronous-written communication.

I started contributing to FOSS over a year ago. Communication was one of the first things I had to learn. I'm still working on it, but I think I've come a long way. Here are some key points I've picked up.

Before we get to the details, I want to preface this post by saying that asking questions and sharing your thoughts is more important than following any guidelines. You can improve your communication as you go, but never hesitate to speak up because you think it's not "well-phrased". People are nice. People will correct you if you make mistakes. So, the first step is to get involved in the discussion, you can then focus on improving. :)

Platform matters

There are various "spaces" where people talk — mailing lists, discussion forums, private chat, issue trackers, etc. Each space has it's own guidelines. It's useful to know these while posting messages.

Mailing lists - Formal, email-like wording is generally preferred. You can start with a greeting and end with salutation+signature. You are expected to add a relevant subject line. Some people prefer to have a word wrap, it improves readability.

Discussion forum - Generally, there is no need for a formal greeting, salutation and signature. It is more informal than an email. Discussion forums typically include IRC, Discourse, Discord, Slack, Zulip, Gitter, Hangouts, and Telegram. Make sure that you understand a little about the platform and the primary reason why the organization uses it. For example, at Bokeh, Slack is used for development discussions and Discourse for community support. Also, note that some platforms like IRC have additional steps like registering your nickname.

Private message - You can generally be as informal as in a discussion forum. There are no strict guidelines here, just be nice.

Mind your language

Always, always, always use inclusive language. I wrote more about this in a previous post.
Assume positive intent - Most people are nice and want the best for the project. Sometimes, their words may come across as rude or hurtful. Start with a foundation of positive intent: no-one wants to hurt you. This will allow you to not take criticism personally, and avoid any unnecessary arguments. That said, some behaviour is unacceptable. If any comments violate the project's CoC, please take necessary action.
Read the room - Try to be mindful of the emotions in the room. I'm writing this in 2020 when the world is having a rough year. Having compassion in your words and checking up on people are small acts of kindness that can go a long way.
Be open to suggestions - Everyone has some value to add to the discussion. Be mindful about giving people a chance to express their thoughts and try to understand their point of view.

Asking questions effectively

Research and be specific - Take a few minutes to Google your question and go through the project documentation before asking questions. Most of the time, you will find the answer without needing to ask someone. If you can't find the answer after say 10-20 mins of searching yourself, go ahead and post the question. Make sure to mention where you searched and what you found. Sometimes, things get buried in the documentation. Asking questions can surface them and the documentation can be improved.
Include all relevant information - If you are facing a software issue, include relevant information like your operating system, environment, software version, browser info, etc. This helps the developers diagnose the issue accurately, and saves everyone some time.
Be bold - No question is a dumb question. Really!

For example, instead of "How do I get started with...", try:

"I'm going through the getting started documentation and I'm stuck at this step. Here is my system information and a reproducible example. I've also included a screenshot of the issue at the end."

Please be patient

FOSS contributors and maintainers are volunteers. After posting a question, be patient for folks to answer. It might take them upto 2-3 days to get back to you. If there is a holiday in their country or if it's a weekend, it might take even longer. If you don't get a reply after ~3 working days, you can follow up politely.

Accent is a speed breaker

This is a fairly recent realization. I have some trouble interacting with people who have a different English accent than me. To be clear, I don't have any trouble in understanding a different English accent, or in speaking English. I just feel like my brain needs to do an extra step of processing and converting before I respond. If you speak more than one language, it's like the bump in the road when you're comprehending in one language and responding in another. (Not exactly, but kind of.)

If this is something you face, it might be a good idea to communicate this openly beforehand.

Resources

How to Win Friends and Influence People, a book by Dale Carnegie
Summer training - Communication
The Secret to Business Writing: Crash Course Business - Soft Skills

Plain English for Beginners

Pavithra Eswaramoorthy — Mon, 24 Aug 2020 14:03:20 +0000

Plain English is clear and concise English.

Technical writing is different from creative writing. The goal of technical documentation is to make complex technical information easy to understand. Hence, Plain English is an important aspect of technical writing. It makes your document more accessible, consistent, and readable.

Why Plain English?

English is not the first language for many people. More people can understand Plain English compared to sophisticated English.
Plain English is easier to translate. Common English words and phrases are more likely to have equally common counterparts in other languages.
Plain English is easier to comprehend. Readers can focus on understanding the technical concept instead of decoding the sentence.

Basics of Plain English

Full Stops instead of Commas

Use short sentences whenever possible.
Avoid combining more than 2 sentences with a comma.

Active Voice instead of Passive Voice.

For example, prefer

"X() reads a new file"

over

"A new file is read by X()"

Cut the Adjectives

Most adjectives do not convey relevant information. For example,

"This well-written function reads a new file"

can be shortened to

"This function reads a new file"

Get to the point quickly and stick to the point.

Inclusive Language and Biases

Avoid using pronouns altogether. If you need to, then:
- use "they" instead of "he" or "she", and
- "folks" or "people" or "everyone" instead of "girls" or "guys". See heyguys.cc.
Avoid racist terms like "blacklist", "master", "slave", etc.
Avoid phrases like "it's as simple as...", "this is an easy step...", etc. What is easy for one person, may not be easy for someone else[1]. Let's not discourage learners by using these terms.
Actively check for biases in your writing. For example, sample names may have gender or racial biases depending on the context. As humans, we may never be completely unbiased. It is still important to educate ourselves and keep trying.

Avoid Jargon, use Common Words

Technical documentation has a lot of technical jargon. Let's not add more. One way to reduce jargon is to get feedback from a diverse range of readers.

Note that slangs are also jargon.

Extra Tips

Planning

It is good practice to plan a document before you start writing. Think about the following:

Intended audience
Scope of the document
Broader context

Structure

Start with a rough structure. Try to split each concept into a distinct section. Clear structure and headings improve readability.

Style Guides

Style guides are standards to help maintain consistency in documentation. Consider adopting a style guide for your technical writing projects, even personal blogs.

[1] I have used "easy" in this blog post. But, note that I'm using it in a comparative context. I say: Understanding Plain English is "easier than" understanding sophisticated English.

Data Visualization - Introduction

Pavithra Eswaramoorthy — Fri, 21 Aug 2020 10:25:19 +0000

Preface

I started planning this series to share my data visualization lecture notes. But, over the past week, it has turned into something much bigger. As I learn more about data visualization, I realized there's more I want to share.

This is not intended as a tutorial or a comprehensive guide. It is just me sharing some notes and thoughts and hoping you find it useful.

What is Data Visualization?

In general, it is the visual representation of some data.

Right? Well... not quite. It is a little more nuanced and fascinating.

Visualization, not data visualization, just 'visualization' is a broad term. This is the visual representation of some information [1]. It can be for the purpose of exploration, analysis, etc.

Visualizations can be charts, maps, infographics, news application and data visualization.

Charts (aka plots and graphs): data presented with symbols that have different shapes, colours, or sizes
Maps: representation of a geographical area or data that corresponds to that area
Infographics: multi-section visual representation of information intended to communicate one or more specific messages
News Application: special kind of visualization that lets people relate the presented data to their own life; mostly interactive
Data Visualization: display of data designed to enable analysis, exploration, and discovery

The boundaries here are not strict. In fact, these blend into each other very beautifully.

Another way to categorize is into information visualization, scientific visualization, geographical visualization.[4]

SciViz: 3d objects used to represent data; often depict flows, surfaces, volumes
GeoViz: 2d or 3d objects can be used to represent data; map-based; uses spacial coordinates
InfoViz: deals with abstract data like hierarchies, networks and multi-dimensional spaces

Data Visualization, in this case, encompasses SciViz and GeoViz. Data Visualization along with Analytics forms Visual Analytics.

Why Visualize?

Authors seem to agree that a primary reason to visualize data is to gain insight. They also agree that Data Visualization is supposed to augment and enhance human exploration and understanding, not replace it.

Another important reason is to convey the truth. 'Truth' is subjective, and we all have biases that tend to push us away from the truth line, but still, aiming for truth is a worthy goal. A step in this direction is acknowledging our inherent biases and actively trying to correct for it. It is also essential to not manipulate the graphs for personal gains - explicitly or implicitly. When I say explicitly, I mean when the visualization is wrong and doesn't present the actual information. When I say implicitly, I mean manipulating the visualizations such that a different message from the real truth is communicated, even if the data is accurate.

One example is this tweet that went viral (kind of) a few weeks back:

// Detect dark theme var iframe = document.getElementById('tweet-1291509085855260672-436'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1291509085855260672&theme=dark" }

The y-axis starts at 5'0'', this exaggerates the difference in heights significantly. If we read the chart carefully, we can tell the difference between the smallest and largest height in the chart is just 5 inches (not a lot!). Hence, this plot is misleading.

Lastly, we visualize because human visual understanding far outweighs any other human senses. We can take in a lot of visual information at once. We can spot similarities, differences and correlations with ease. We can also make some information pop-out.

How Do I Learn Visualization?

This is something I had to figure out before jumping in. There seem to be different aspects of Data Visualization that I need to learn. These can also be thought of as different ways to learn data visualization.

First, we need to look at the different types of data and how they are represented. Data can be categorical, continuous, discrete, etc., and it can be represented as text, tables, images, etc. Once the data is understood, we can talk about the idioms (viz techniques) that can be used to visualize them.

Second, there are some best practices, ethics and rules for creating good visualizations. The y-axis manipulation example is just one not-so-good practice. We can talk about different idioms and explore the best practices for each. For example, the use of size, shape and colours to represent data - when to use what.

Third, we need to learn to use some data visualization tools effectively. There are many tools available. The tool of choice depends on our use case. In this series, we will mainly be working with Python - Matplotlib and Bokeh.

Finally, the more we learn, the more things there are to learn. For example, interactive plots can be explored in-depth, we can discuss the above three aspects individually for interactive plots too! I'm excited to see where this series takes us!

References

I referred to the following books to write this blog post:

[1] The Truthful Art: Data, Charts, and Maps for Communication by Alberto Cairo

[2] Fundamentals of Data Visualization by Claus O. Wilke

[3] Data Visualization: A Practical Introduction by Kieran Healy

[4] Visualization Analysis and Design by Tamara Munzner