Communication Guide

Improvements? Suggestions? email dna@hola.org

Consistent

Be consistent with the style of communication you receive from veterans in the company.

Email

Effective handling

We adopted several email guidelines from Eric Schmidt's 9 rules for emailing: Why?

  • Respond quickly
  • When writing an email, every word matters, and useless prose doesn't
  • Clean out your inbox constantly
  • Handle email in LIFO order (Last In First Out)
  • When you get a note with useful information, consider who else would find it useful
  • When you use the Bcc (blind copy) feature, ask yourself why
  • Make it easy to follow up on requests. When you send a note to someone with an action item that you want to track, copy yourself, then label the note "follow up."
  • Help your future self search for stuff. Forward yourself emails along with a few keywords that describe its content

Manage your inbox

Email responsiveness and never loosing an email (forgetting to respond) is critical for efficient and reliable email communication with our peers.

Respond quickly

Respond quickly to email. Many times a day check your inbox, and handle the 'tiny' emails immediately. Handle the new email in LIFO order: this improves responsiveness - one 'heavy' email will not block responding to 20 'tiny' emails coming after it. Also if there are many emails on the same subject (email chain), its easier to read them from the end-backwards.

Empty out your inbox

Why?

Empty out your inbox constantly: never end your day with more than 10 emails in your inbox.
What if you have 'heavy' email - email that requires a lot of work (e.g. writing a complex module), or cannot be handled immediately (e.g. switching hosting provider next month)? Move it to long-term task queues, such as version plan or your calendar. In such cases email the requestor the target date you planned for completing this task, and when that date arrives - send a completion email (or a postponing email, if you decided you would like to postpone).

Archive. Don't rely on 'read' status

Move emails from inbox to Archive (or Trash) after handling. Don't rely on 'read' status (or any other tags or labels) to mark which email you handled and which not. GMail and Thunderbird have a 1-click "Send+Archive" button to make this easy.
Why? Every time we investigate the root cause of email loss (someone missing out an email - forgetting to respond on it), we found the cause was relying on the 'read' status or some label inside the inbox as an indicator for handled email.

Archive. Don't sort.

Don't sort mail into folders for easing later lookups and searchs. Just click Archive - so it all goes into one large Archive folder. Just like in GMail: archive all handled email to Archive folder, and if-and-when you need to lookup an email, use the powerful search capability.

No filters

Instead of filtering incoming email, just remove yourself from notifications that are not relevant to you. If you don't know how to un-subscribe from a certain system, ask the IT team to un-subscribe you.

Online. No local folders

Email must all be online, available from all devices. Therefore never use local storage folders - which are offline and not available from all devices.

Minimal

Be minimal: shorter emails, less emails, and prevent email threads by writing better emails.

No styling - pure plain text

Do not send 'rich' HTML emails: no fonts, no colors, no bold/italic/underlines. Nothing. Just plain text (attachments are ok).
Styling makes the emails easily corrupt and un-viewable on different email clients, and also shift the focus from content to presentation. At Hola we try to focus purly on content and value.

Minimal recipients

Before sending an email, go through the To and Cc, validate minimal list of people in To (best if only one person with the action item), and minimal people in Cc.
If it is a reply, rethink before sending: do all these people have to be included?
Just about to send a mass email out to an 'all' mailing list? Think again; can you avoid it by sending to only specific people?. Is the info really needed by everyone? Perhaps you can provide the info 'on-demand' by putting comments in code, explanations in web pages where relevant, or adding info to a howto.

Single To

Generally avoid sending an email with more than one person in To. If the email contains action items for multiple people (and thus multiple people in To) - then clearly mark on every AI who is the relevant person who needs to act/respond on that item.

Subject filter

If the email is not relevant to all, but you don't know exactly to who - so you cannot reduce the recipient list, add a "filter" (who should read/ignore this email) message in the Subject, or the first line of the email, before the "Hi".
Example of a filter:

Simplified technical English

Use only simple technical English. Avoid using "political" English. Excessive use of words, explanations that refer to the emotions and beliefs are making your arguments obscure and might turn the discussion to a long and tedious one.
This statement:

Should be written like this:

These should not be written at all:

Attachments summary

Whenever attaching a document (text, spreadsheet or presentation), write in the email a tiny summary. The recipient then has the choice not to open the attachment.

Action items (AI)

Make discussions actionable

Briefly state what the information is, what you learn from it, and what your next action will be. Don't:

According to Google Analytics, our traffic on the index.html went up 20% and so did the bounce rate.

Do:

According to Google Analytics, our traffic on the index.html went up 20% and so did the bounce rate. I will work on reducing our bounce rate. Avi: please find the root cause of the traffic increase so that we can learn how to leverage it further.

Mark & clarify action items

If the email has no AI, state that at the top (e.g. FYI). If there are AIs to only a part of the receivers, put those people in the 'To' and state at the top of the email who has the actions. If there multiple AIs or multiple AI owners, list the AIs each with the schedule and owner name.

Immediate action

If the action requested can be done immediately, do it and reply with a one-liner email as soon as it is completed. Send a diff URL (or attach a tiny screenshot if applicable) in order to receive immediate feedback.

Delayed action

If the action requested is not to be done immediately, respond quickly with the expected time of completion and if possible with a partial solution or response.
Log the action in your version plan. Make sure to track it. If you will not be able to complete it on time send an email updating with the new expected time. Once you've completed - send an email notifying the requester

Partial completion

If the action requested was partially completed, reply with the status and notify the requester of the full completion time. Continue the request handling the same as you would with a delayed action item.

New email

Template

Always include a Hi opening and sign your first name at the end, give meaningful subject, and concise body.

Informative clear subject

Give an informative, short and concise subject to the email.
The subject should briefly describe the contents of the email. If the email is a little long, use the first line to explain it in one sentence. Never send an email without a subject. If you received an email with a bad or missing subject, modify the subject when you respond.

If it might not relate to all people, explain in the subject or first line who should not read it.

Tiny Greeting

Always include a Hi opening, and a spacing line after it. Why so short? Minimalism. Why always include a greeting? in long email threads the greeting/signature are used as begin/end markers to know where each email begins and ends, and who wrote what.

If the email has more than one person on To, but you want major attention from one of the people out of the To list, you can add his name in the greeting.

Tiny one line emails

If your whole email content can fit one line, then just send it in the Subject, with and empty body.

If you have 1 line of content, you can skip the Hi greeting.

Simple lists

Use '-' by default for bullets. Don't number bullets unless you specifically refer to them.

If the bullets are "status report" of tasks, use the style defined for version plan.

Subject only email

When possible to compose a clear email without a body - do it.

Signature

Short emails are much appreciated. Long multi-line HTML signature, with fonts and lots of info and links just make email threads overly long and hard to read.

Short signature

Just your personal name. Nothing else!
Use this for 99% of your emails: all internal communications, and external communications which are 2nd and onwards email with that customer, such as in replies to email threads.

Long signature - avoid it!

Try to avoid it. In any case, never use long signatures in internal emails.
Use long signatures when this is your first communications with an external contact, since we try to give direct personal contact details to external people we communicate with (such as phone, IM...). For repeating communications with the same external contact, switch to the short signature.
Create your long signature using the signature designer. This validates it matches our well-defined format of one single long line.

External template

External emails may have a little more relaxed greeting: you may replace Hi with Hi Brad. You may also decide to insert your Long signature instead of the short signature. We recommend to normally use the long signature in the initial communication with that recipient, and later on move to short signatures for same recipient. Be personal: If further vocal communication needed, give them your personal mobile number/Skype/hangouts/etc so that they can contact you directly.

Action required email template

Email subject should contain "ACTION REQUIRED:" in capital letters.
Email should contain defined steps to achieve the action.
Email should contain a deadline to complete the action.

Incident report email template

Email subject should clearly summarize the incident.
Email should contain a full timeline of relevant events.
Email should state the full impact of the incident (servers/customers/downtime).
Email should identify all the problems that lead to the incident, and suggested solutions.

Replies

Untouched original

Leave the original message untouched, at the end of the email, after your signature. If this reply turns into an email thread, everyone will have full information. Make sure you are using Reply All keeping everybody in the loop.

Email reply quotation

When you use quotation in reply to emails, leave a line between the quotation and your answer(Why?). When answering a question: feel free to minimize or rephrase the quotation to focus and improve clarity.

BAD example of NOT leaving en empty line between the quote and your answer:

BAD example of putting your name before your answer:

GOOD example of how quote and answer should look like. A quote then empty line, then your answer:

Answering questions

When you have received several questions on an email, give an answer to all of them. Answer each question separately - quoting the original question.

Referencing

When referencing previous items from the current or from a different email thread, quote the original item to spare the recipients the search for that item.

One line replies

Single line emails do not require Hi and signature.

DONE replies

We usually using such replies to tasks we received, done/fixed/implemented and deployed.

Added to VP replies

Sometimes, you cannot act immediately.
In such cases log it in your version plan and provide a tentative optimistic quick 10 seconds estimation, when will you handle it and when it will be DONE.

Why replies

Once getting a 'why' email you need first to understand whether it was a mistake or not - this is the first step to take a productive action, and it should be the first line in your reply. e.g. NOT A MISTAKE or MISTAKE.
In case you think it was not a mistake, explain why makes you think this way - provide facts and data. In case you understood it was a mistake, explain how you are going to fix it as well as prevent others from doing the same.

Reply for feedback

When you've received an action item and you're email reporting on its completion or progress, attach a visual aid to receive immediate feedback on the result.

  • When reporting on completion or progress of a GUI change, create a tiny screenshot or animated GIF of the result, highlight your modifications (if needed) and attach it to your response.
  • When reporting on completion of code modification - send a diff URL of this code.

This will minimize the iterations and will speedup process.

Choose specific wording and provid ETAs for tasks you do rather than using vague time frame.

I'm investigating it now and will report back soon.

"Soon" is hard to work with. We give ETAs, and later update if we are not delivering on time to advise of the new ETA.

I'm investigating it now and will report back on 17:00.

To vs. Cc recipients

If the email is mainly to one person, but there is AIs for other, anyone with AI must be on the To list (never Cc). In such a case add to the Hi the name of the main recipient.

Adding people to the discussion

In case you would like to add more people to the discussion (email thread), use 'Reply All' and add them to the Cc or To as well as notify everybody on their addition.

Or answering, while adding to the discussion:

Removing people from the discussion

If you would like to remove non-relevant people from the discussion, use 'Reply All' and remove them from Cc. Then add to the email that they were removed.

Instant messaging

IM is an interactive way to communicate remotely. You need to respond fast and be precise and specific to allow a fast flow of conversation.

Fast response

Respond fast, like you are talking f2f to your peer. Remember he cannot see you, so any other reaction but text message is not acceptable.
So, possible reactions to several scenarios:

  • Do not know the answer to a question, text "do not know"
  • Need some time to look for an answer, text "looking"
  • Need to search the Internet to bring some data, text "searching"
  • Got a task and you are going to do it, text "ok" or "added to VP"

Meaningful and actionable

Don't just say 'hi' as first message. Say what you want!

me: Hi
arik: Hi - what do you want?
me: Can you check broken link on BAT?
me: Hi - can you check broken link on BAT?
arik: checking

Short text

Minimize your text to include only relevant data. Be accurate and clear.

me: Hi Arik, r u there?
arik: what's wrong?
me: batlinux642
arik: what happened?
me: batlinux642 is broken. did you break it?
me: batlinux642 is broken. did you break it?
arik: checking
arik: yes it's me. fixing it in 2 min.
arik: I need you to do some testing
arik: It is blocking me
me: few minutes
arik: I need you to do some testing
arik: It is blocking me
me: talking to roman, few minutes

Identify yourself

We are using different messaging tools that cover our identity, e.g using WhatsApp from an on-call phone, using single Skype account by several people etc. Since we're working p2p it is important to identify yourself.

deploy: batlinux642 is broken. did you break it?
arik: who is it?
deploy: nir
arik: checking
arik: yes it's me. fixing it in 2 min.
deploy: it's nir. batlinux642 is broken. did you break it?
arik: checking
arik: yes it's me. fixing it in 2 min.
arik: fixed

Notifications

Set your skype 'mood' according to your current status. This way, it will be easier for your peers to know if you are available.

Update with an away status

Away till 16:00

Update that you are on a vacation

Vacation till 29-Aug-2016

Update that you are at lunch

At lunch

Update if you are working from home

WFH

Tasks

Being productive remotely (alone, no one sitting next to you) is much harder than in the office (together with your peers). Due to this, very few companies work completely distributed, where every developer is in his home, in a different city and country. To be able to succeed in being productive, in spite remoteness, requires meticulous communications of tasks, during the complete task life span.
You have a small question? You cannot just turn around and ask your peer a question (... which happens to also be your office-mate) - your peer may be 10 timezones away from you. So you must reduce round-trips, increase transparency by sending many regular updates, and be quick on feedback.

Heads up

Planning on starting a new task? Try to think who may be relevant/interested, and email them a heads up about the task, and when you plan to actually start working on it, and when you plan to complete it.

Delays and cancellation

You told you will do something and you decided to delay the start of the task or you decided to cancel? email the relevant people on this change.

Started working on it

Email relevant people that you started, and your updated estimation of when you plan to complete.

Incremental/partial results

You have something basically working - email a screenshot! Offer people to connect up with screen-sharing and play around with it. Even before its fully written, passes unit-tests, ready for commit... You will receive feedback eariler this way.

Completed

Once the task is completed and deployed, email relevant peers send some screenshots, link to commit, the URL they can see this feature and play around with it.

Wording

Use simplified technical english, not 'political english'.

Keywords

URGENT

Should normally be 1st word in subject, for things that require an action that same day. Typically we also call the person up directly on phone/im.

AI (action item)

See the AI section for examples.

ACTION REQUIRED

When there is a tiny specific & immediate action that needs to be done.

DONE

Normally as a response to an action item email. Can be used as a single word response.

FIXED

Similar to DONE, but refers to a problem that was fixed.

FYI (for your information)

Informs the recipients that this email (or a section of it) is not critical, and nothing 'bad' will happen if they will skip it/ignore it/read it later. This helps the recipient to prioritize his inbox.

Date format

Use only or DD-Mmm-YYYY (or DD-Mmm-YY), or just DD-Mmm to keep it short.
This format is clearly understood by all, regardless of locale.

15/1/16
2016-15-01
15-Jan
15-Jan-16
15-Jan-2016

Time format

Never use AM/PM.

9:30pm IST
21:30 IST

Always 2 digits for hours.

9:30 IST
09:30 IST

Timezones: Technical (commits, releases, deploy, server events...) - UTC

12:30
12:30 UTC

Timezones: Human (meetings...) - Local time of the person you are communicating with.

12:30
12:30 IST

Grammar

Questions

Questions need to end with a question mark.

Has your team decided yet.
Has your team decided yet?

Punctuation

Punctuation marks like !?. and , always come directly after the word and have a space or new line after it.

Has your team decided yet ?
Has your team decided yet?
I'll explain,shortly, about Spark
I'll explain, shortly, about Spark

When & replaces a word, it should have spaces around it. Better yet, use and instead.
It is OK to use & in company names like AT&T or common short forms like R&D, but most communcation should use and.

I'm free today&tomorrow.
I'm free today & tomorrow.
I'm free today and tomorrow.
We will need a day of R&D to make it work.

Capitalization

Capitalize the beginning word of a sentence.

we will handle it soon.
We will handle it soon.

Capitalize proper nouns (like the names of people, places, companies, holidays).

I will touch base with nir after christmas.
I will touch base with Nir after Christmas.
I have a call scheduled on Tuesday

Don't capitalize yesterday, today, or tomorrow unless they come at the beginning of a sentence.

We'll talk Tomorrow
We'll talk tomorrow

If you're not sure whether to capitalize or not, don't. An incorrect capital looks worse than an incorrect lowercase.

Short forms

Only use short forms if it is common and the original word is long. Often short forms are hard to understand.

We'll talk tmrw.
We'll talk tomorrow.
It will take approx. 2 days.
It will take approx 2 days.
It will take approximately 2 days.

Never replace a word with a number or a letter.

I'll send it 2 u.
I'll send it to you.

Well hello there!

We're in the process of giving our website a
new look, call it a makeover if you prefer :)

Rest assured, this will be updated soon too,
we're on it.