Hacker News Reader

I've found it useful to distinguish between the times I'm asking for something, and the times I'm documenting something.

When asking a question, lead with the question, and put only the bits you need to clarify your question underneath. For these communications, the shorter you can make it, the better.

When writing documentation, you're writing for the future, and should aim for completeness rather than full comprehension immediately -- you want something people can look back at later when they're not clear on something, rather than something that your reader will read in one sitting and remember flawlessly. Your reader isn't going to be able to retain that much stuff.

If you absolutely need your reader to understand some points, I recommend keeping the points as short as possible, and also to your point, asking a question that requires them to have understood what you wrote (e.g. "people who signed up before this date will be grandfathered in, so may see different rates than new customers. Are you aware of any marketing material which might give conflicting information? " -- the answer is probably "no", but in the course of answering that question, they had to understand what you were saying, and as a bonus if the answer is "yes" you've avoided a problem before it happened).

One of the hidden assumptions in "hire people that write well" is that people who write well would also likely have high reading comprehension skills. Or, the inverse—I find that the ones who want to jump on a quick call vs. writing out their request are the same people who seemingly don't read the documents I produce.

Quickly reading and understanding almost everything I can find—code, plans, schedules, calendars, strategy, memos—is how I excel in remote environments. It's not a huge time commitment, 20 minutes a day, but I have the organization's "state" modeled in my head, which helps me identify dependencies and potential bottlenecks before they're surprises.

Different people have different communications styles, and resolving that is always tough. But there are definitely those who communicate poorly in any medium -- and I find that often they're the ones who like media where they don't leave a trail that can be pinned on them.

There are are advantages to the "quick call", and some people definitely work better that way. But I much prefer written communication: not only do I get to refer back to it, but it's more asynchronous, freeing me up considerably.

"Let's talk" often seems like a barbarous imposition on my time, that I have to hear it right now and make any decisions while you're staring at me. I try to keep in mind that they just have a different communications style, but that's not always easy.

> You can write the perfect email, and there will always be someone who will misinterpret it. The problem is not merely in the content, but in the other (including their worldview, culture, social status, etc).

Without a doubt the first sentence is true. Successful written communication requires properly encoding the information (writing) and properly decoding it (reading). A flawed reading of an email means communication breaks down independent of the quality of the writing.

The second is also true, but incomplete. In many cases, there is a failure to read (either because of laziness or "I already know what he's going to say") or a language issue - even for native English speakers. It's not at all uncommon for someone to miss a "not", think "and" rather than "or", interpret "weeks" as "days" and so on.

Edit: One story that comes to mind is related to a policy our department was implementing a number of years ago. I sent an email with what I thought was minor supporting information. I got an angry reply of six paragraphs, totally irate that I would suggest something so crazy, listing all the ways I was wrong. I responded to say "I think you read my first sentence wrong." The response: "Oops!"

Put your ask at the top, don't be afraid to use bullet points, keep things short and sweet. Most things can be effectively communicated in 2 or 3 paragraphs - if you need to communicate more than this, send it in a follow-up email after they respond. If you need to communicate more than this, you should really set up a quick call to communicate the thing and ensure they understand, then send the long email afterward.

Using checkboxes in GitHub issues is my secret weapon. There is no way to mark an issue as done or glaze over the details that way. Checklists in general are a great thing. I wish there was a startup that made community sourced checklists for common tasks like opening up a PR or writing an email asking for a raise.

Checklists also save lives!

> But a year after surgical teams at eight hospitals adopted a 19-item checklist, the average patient death rate fell more than 40 percent and the rate of complications fell by about a third, the researchers reported.

https://web.archive.org/web/20151103232100/http://www.nytime...

on the flip side of this, there’s those of us who hate the superfluous (opinion) processes that seem only to slow down, not speed up.

PRs don’t need checklists IMO. If they do maybe your team is too large.

I think a little checklist would help me remember things that are easy to forget, like updating documentation or making sure that a test exists to reproduce the issue. That said, at the end of the day tools exist to help us, not slow us down. If they is a small PR that fixes a typo then I want to be trusted to skip the checklist completely.

Have you tried putting each important sentence on it's own paragraph? Just the important ones.

That makes a difference in focus/readability.

Try it.

Take this too far and you end up writing broetry.

After enough years in a corporate setting I can guarantee that this has the opposite effect, because it makes it even less likely for your email to fit on a screen so it just gets skipped.

Many of the suggestions I'm seeing are the polar opposite of how this thread started.

When you're remote you miss a lot of context. Overcommunicating in writing helps address that. Eliminating information or not expecting people to fully read and engage with what they read is going in the wrong direction of the fundamental problem.

If an email is too long, then some will just ignore it. So overcommunicating can lead to people ignoring your essays for a simple point. Then there’s the time aspect. With everybody overcommunicating how will work get done with everybody overcommunicating to discuss a bug? Some of the most productive teams I’ve been around and on barely needed any communication outside of quick alignment meetings. Seems this is very opinionated, rather than fact.

As an IC you probably have more time to fully read emails, esp. those from your management chain.

I like to lay out the decisions I'm going to make if I don't get feedback, if possible. That seems to prompt feedback when feedback is required -- it seems the human desire to fix mistakes is stronger then it is to answer open ended questions. It likely gives the reader some context as to why you need the information as well.

> As an IC you probably have more time to fully read emails, esp. those from your management chain.

I’m sorry, an IC having time?

You're totally right that you have to know your audience and cater to it. Technical writing still requires it.

What changed my perspective though is the book "Comedy Writing Secrets". It's a very different topic, but the general aspects of writing fun an engaging texts translate quite well.

One example I've seen it done brilliantly is the re-frame docs https://day8.github.io/re-frame/re-frame/ - I often point it to people as an example of technical writing so good, that its fun to read just for the sheer pleasure of it, regardless of whether one writes Clojure or not.

_why's (Poignant) Guide to Ruby is also a famous example of this.

> As I said: You can write the perfect email, and there will always be someone who will misinterpret it. The problem is not merely in the content, but in the other (including their worldview, culture, social status, etc). The solution isn't to try to become a more perfect writer, but to understand the dynamics involved in communication (written or verbal).

Wiio's laws are always relevant: https://en.wikipedia.org/wiki/Wiio%27s_laws

The main thesis being "Communication usually fails, except by accident".

It’s a bit like sending events to an unknown state machine.

You need add enough context for the event to be processed but you can’t know what will happen when it is...

>people rarely read my emails if it doesn't fit in their screen

I think this is the case unless the problem is very relevant to what you are working on at the moment. Normally what I would do, if I were writing an email to explain a problem, is create that explanation in depth on a wiki or other knowledge repository somewhere. Write the email referencing the url of this wiki, and explain the main points in the email.

This is as a general rule if I am explaining something important for tech team to know, if I am explaining something that is important for product owner to know I write it in as verbose an email as is required to explain everything. That's up to the product owner to follow. Generally after receiving an email like this they will want a meeting where I can explain in person and draw stuff on the whiteboard.

The One Palm Rule. I know a few people that promote this :) If it's larger then your palm, when you streach a hand towards screen, you are not obliged to read it.

Suprisingly effective, especially if you are open about it. Of course it applies only for those with 1000 unread (after filters).

I can't fit your comment with my palm on my current monitor.

(But I read it anyway.)

I guess the effect of following this rule depends a lot on formatting, size of hands and monitor and how long your arms are and how far away you are standing.

You are holding your palm flat towards screen, right? :)

It's one of those things you apply only when it suits you, and ignore when it doesn't work to your benefit.

Jokes aside: I wrote this because it's both sad and interesting how people cope with huge amounts of communication that waits for their action.

I was working a pretty big screen at the time.

You are right, of course, though this may seem to conflict with my original comment. One way to reduce email size is to put context information into reference documentation. (Or other substitutes, like Github issues, JIRA, design docs, requirements, operational run books, etc.)

One thing that may not work very well is depending on Slack channels or other chat systems for context. It's fine for an on-going issue but does not work for general information. Important topics are just too hard to find later.

Be mindful of how Outlook displays messages. Subject should be the topic, and the first line should be the ask. That way busy people see everything they need in the preview, without ever opening the email.

Have you considered refactoring info into wiki webpages and hyperlinking between them? Then your email can link to that.

> As an IC, people rarely read my emails if it doesn't fit in their screen (so 3 paragraphs is the max).

You need to learn how to restructure your writing. Most logical people naturally write in a way where it’s premise, premise, premise, conclusion. Instead, you need to write conclusion, premise, premise, premise.

One way I’ve found to help my team learn to write this way is to institute a rule that any writing longer than 3 paragraphs has to have a TL;DR at the top that is no more than 3 sentences. This gets people over the hump of putting the big ask up front and then after a few weeks, they start naturally writing that way.

This echoes OPs point about culture. One absolutely should not do what you've mentioned in my location. Here we lay out the arguments, and the conclusion at the end. The reverse is seen as jumping the gun, and not being well reasoned. It is looked down upon, and frequently discounted immediately.

Cultural bias is very much a thing.

How is that cultural? Even through elementary school we were taught to have an intro with what your point is, follow up with supporting arguments, then conclude by reiterating the point the you made.

How could you read anything without knowing the point in the beginning. Even research papers start off with an abstract.

The fact that you was taught that in elementary school and thus literally concluded that it is impossible to read something without knowing conclusion first is what makes it cultural. The fact that he and everyone around him sees conclusion up front as jumping the gun and likely was taught that structure in school, is what makes it cultural.

> How could you read anything without knowing the point in the beginning. Even research papers start off with an abstract.

It is pretty easy to read email or argument without knowing the conclusion up front. You just read on. Research papers are specific writing with specific rules. I dont really think they are in general example of good or persuasive writing.

It doesn't make sense as being cultural because there plenty of real examples of effective writing that starts with what you are writing about. The only exception might be in story telling, but that only works because there is some kind of context assumed or it works as a tool.

It makes no sense for this "culture" to think less of research or any writing that intends to persuade because it starts with a introduction or summary. Anyone who starts with a summary of what is going to follow will be a more effective communicator. They would be missing out on lots of writing that is done this way.

Your first paragraph or sentence will always be an introduction. If you choose to not take advantage of it to set the context of what follows the writing will be more confusing or require a second read through. Its like wandering through a forest vs following a trail map. At work, writing something that needs automatically needs a second read through is a problem.

I guess i have hard time believing this culture exists the way is presented, and isn't being misinterpreted.

> It is pretty easy to read email or argument without knowing the conclusion up front.

Its not, that was the point of the thread were commenting on

> Research papers are specific writing with specific rules. I dont really think they are in general example of good or persuasive writing.

This is one example, it has rules because those are effective at communicating. How can you just write it off like that? With no reason other then you think it doesn't count?

> It doesn't make sense as being cultural because there plenty of real examples of effective writing that starts with what you are writing about.

That argument does not make sense.

> It makes no sense for this "culture" to think less of research or any writing that intends to persuade because it starts with a introduction or summary.

And it does not make sense for you to look down at writing that puts conclusion to the end going with arguments first. It is just an habit and meaningless difference, that is all.

> This is one example, it has rules because those are effective at communicating. How can you just write it off like that? With no reason other then you think it doesn't count?

Researchers and their papers are not effective at communicating. That a thing that researches complain about periodically.

In any case, corporate mail is not research paper. Among other things, it is supposed to be significantly shorter. Just like it is not newspaper article.

Can you show me something written that doesn't have an introduction that includes a summary of what's to come

> It doesn't make sense as being cultural because there plenty of real examples of effective writing that starts with what you are writing about.

This is a non-argument. In the US, writing is considered effective if you put the bottom line up front. GP wrote that BLUFfing is considered offensive in their culture. Now you respond that lots of people like BLUFfing.

Now you say it's not culture-dependent but a universal truth that BLUF is better.

Well, other cultures disagree.

Bluf seems to be a specific thing, no one mentioned that in the thread I'm commenting on.

The post that I responded to suggested having an intro with a summary of what's to follow is offensive

You could still totally just read the ending first if it's that big of a deal for you.

This approach depends very much on culture. For example, US culture is very much, get to the point, start with the conclusion. German culture requires you to outline how you got to the conclusion.

Interesting book on this topic: The culture map, by Erin Meyer. (https://www.amazon.com/Culture-Map-INTL-ED-Decoding/dp/16103...)

It has a whole chapter on this topic: 3 - Why versus How, the art of persuasion in the multicultural world.

German culture requires no introduction in any writing? Am I talking about the same thing as everyone else commenting?

Anything you write will always have a first sentence or paragraph. Your saying it's offensive to use that to give an overview of what's to come and to set the tone of the writing?

Looks like i wasn't very clear.

The difference according to the book is that if you want to convice an audience of something, e.g, result of a study, americans are more interested in the results and how to apply it. Germans want to understand how you got to the results, what the process was behind it so they can understand that your results are correct.

> One absolutely should not do what you've mentioned in my location. Here we lay out the arguments, and the conclusion at the end. The reverse is seen as jumping the gun, and not being well reasoned. It is looked down upon, and frequently discounted immediately.

I would like to understand why the reverse is "jumping the gun". I am assuming the arguments have not changed, the reasoning remains the same. Why is a mere change of order "jumping the gun"?

Theory: If people read conclusion first, then people tend to evaluate whether they agree or not after reading conclusion. Emotional reaction toward conclusion will bias interpretation of arguments.

The remaining arguments are more likely to be accepted or rejected based on what you know conclusion is. So instead of asking "is this true", people will start either with "I am looking for nitpick cause I see this is going toward bad conclusion" or with "yeah sure, it shows what I think".

However, they will still feel like they evaluated arguments on merit. If the conclusion is last, people can and some will go back to arguments to bias them, but it is easier to see what they are doing.

While the solution may be valuable, there's more value in reading the work to get there. Rarely is the value a decision, inasmuch as the path to the decision. By first declaring a solution to a problem, you're priming the other individual. Depending on their personality you're priming them to be for, or against your decision.

By articulating the reasons, methods, and considerations that went into a decision, you're slowly and softly building an argument. Individuals are less likely to have an instinctive reaction to something this way. At the very least, it's proven (yes, as in measured) to be the case here.

I have experience at several companies with many different cultures, and I don't know of anyone who likes to slog through the details before getting to what the final problem or solution is. People just don't have time for that. Putting the important part first serves the dual purpose of quickly informing people who aren't interested in the details, and telling them up front why they might care about reading the details.

It's like having an abstract or a blurb to briefly summarize for management.

Similarly, if you need someone to take action based on the result, you don't put it at the end where nobody's going to read it. You put it at the beginning, first thing, and then build up the background.

That's a really interesting counter-example to what I've learned as the best way to write.

Can I ask what culture you're referring to?

We called this BLUF: Bottom line up front.

pick up the phone