How to effectively communicate technical data/instructions without writing "too long" emails? [closed]

Question

I frequently find myself writing emails or technical documents that include a lot of technical information. However, even when written to "technical people" about technical things, it seems that the length of the email is too long and therefore it goes unread, ignored, skimmed, etc. and I've become known as a long-winded person. I'm starting to get flak for that, and I'd like to understand why or what I can do about it.

How long is too long?

It seems that the length of "too long" is absurdly short; longer than a couple paragraphs is considered too long.

What are the details?

Most of the reason for the long-windedness is an effort to be thorough, reduce known/possible miscommunications (some of which are highlighted below), and deal with the fact that the "technical" people aren't very technical, nor competent. Sometimes the lack of competency is known (I'm instructing someone for the first time in something they've never done), and sometimes it's because they are deficient in prerequisite topics (common in my industry; explained below). Often, I include screenshots with notations, and I leave them large to be easier to read. That increases a page count quickly.

Feedback I get (from bosses and coworkers) is that such lengthy emails/documents are unwelcome and unwarranted, with an emphasis on time spent.

Possible solution: Executive Summaries

I've started to include an executive summary at the front, but I think I've passed the point of no return, and the email gets ignored or stays unread. Part of that is because most people in the industry are overworked, part of that is email culture is to ignore things, and part of that is any reputation I have for being long winded.

Boiling down something to an executive summary may still be too complicated (another problem I deal with), or they feel like I'm being overly vague, arrogant, or condescending. I haven't gotten much feedback about this in written form, but when I do that face-to-face, it's obvious they think I'm being overly vague.

Possible solution: 6th grade reading level

I was once told to keep emails and docs at a 6th grade reading level. Attempting to do this was met with some success, until things became complicated enough that I had to start expanding them. It's not easy to break things down into less complicated chunks, and often that means they wind up being bigger chunks.

Some examples:

Table of Contents

I was handed a project to start working on, and as I went through the existing documentation, I wrote down questions and commentary ahead of a planned meeting to go over these sorts of things. It was ~8 pages, so I used the auto-format capabilities of MS Word to generate a Table of Contents (ToC). This takes all of a minute or two and makes it easier for the reader. However, my boss, who was CC'd when I sent the document, clearly didn't like the ToC and was stuck on that, bringing it up anecdotally in a different meeting with no relation to this project. I think it was because he didn't know how easy it was to make, nor how to use it. I think ToCs are incredibly useful since they are CTRL+clickable.

Clarity vs brevity

I tend to remove pronouns and references in my written works because I find most people can't find the thing I was referring to, and stick on the wrong one. For example, above, I changed

I think they are incredibly useful since they are CTRL+clickable.

to

I think ToCs are incredibly useful since they are CTRL+clickable.

so that it was unambiguous that I was referring to ToCs. This may come across as off-putting, but I'm not sure.

Lack of "basic" skills

While my industry works with technology, the people in it are usually not very tech savvy. For example, only very few of them (~1/10) know about keyboard shortcuts like CTRL+C, CTRL+V, or that most programs have a search function built into them.

Poor reading/writing skills lead to brain overheating

I also find that people don't know how to use certain punctuation marks and therefore use them wrongly. I've discovered that people use quotes ("") to emphasize something, instead of to satirize it (like I did above for "technical people"). The former should be bolded, while the latter is often referred to as "air quotes". I've also seen people confuses slashes with commas: this is the same/similar, yet people would write a list of items as a/b/c/d, when it should be written as "a, b, c, d.".

I suspect that when presented with technical data in a technical format, or just unfamiliar formatting, the reaction is a brain overload, or anger and resentment that they are unfamiliar with something.

Region

I'm in the US, and all of these problems come from people who were born and raised in the US, almost exclusively within the same geographic region.

How can I more effectively communicate in emails to my coworkers?

Answer 1

A short email is harder to write than a long one. People are telling you to take the time and put in the effort to write a short one.

Let's say you're writing an email about how to boil an egg. In some sort of self-defense to ward off problems that have happened before you include sections on how to choose the right pot, a detailed discussion of the various sources of water for filling the pot, and a section for both gas and electric stoves, as well as how to tell which kind you have. 7 pages in, you mention to put the egg in the water, and three pages after that you say to start the timer -- perhaps when the egg is put in, perhaps when the water comes back to the boil. You include several videos to be clear about whether water is boiling or not, because these people aren't technical and you can't be too careful. After the videos, pages away from saying to start the timer, you indicate how long to boil the egg for, and then there are several more pages of vital details about egg-cups, spoons, knives etc and an appendix on running hardboiled eggs under the cold tap and what causes that green ring. Nobody can find the "ten minutes" in all that. They are frustrated by the huge long irrelevant thing you wrote.

What they want from you is to mention the water, the pot and stove, when to put the egg in, when to time from, and how long to cook it. That's easy to know about egg-boiling. It's hard to know about your subject.

An email is not a course. It's not a manual. It won't defend you from trouble. It is hard work to extract the absolutely vital pieces of information from the trove you know, and share just those with the people who need them. You are being told you should do that work.

In your emails, tell people the things that they need to know and would not think to ask if you didn't tell them. Include links to more detailed background they might need, or include documents as attachments and explain the circumstances under which the attachments will be needed. If something is tricky or depends highly on something else, it's ok to say "we may need to de-frabulate the syscomator at this point, but if so I will notice and let everyone know," or "at this point it's important to do nothing for 24 hours so we can tell whether or not I need to de-frabulate the syscomator" without including a simple ten page summary of that process. They don't need to know those details. They do need to know about the letting it sit. You need to put in the work to establish what they need to know in this email, which is less than everything they need to know ever.

Answer 2

Your personality leads you to always write a certain style of email.

Your style is aimed at communicating detailed and unambiguous information which covers all reasonable eventualities.

You get flak for these answers, they go unread, get skimmed and ignored.

The emails get skimmed and ignored because, despite your laudable aims, your communication style is not appropriate to the recipients. It may be the information you believe they need, but it isn't the information they want, presented in a format accessible to them.

This isn't so much leading horses to water and trying to make them drink as carting several gallons of water to horses that had merely expressed a desire for a couple of sips.

People may be frustrated and annoyed for several reasons:

• they are not easily finding the information they wanted from your answer

• they may resent you apparently having the time to compose multi-page emails which they see as being bulked out with irrelevant information

• They may feel you are grandstanding or showing-off, perhaps even trying to belittle them.

Your aim of trying to communicate effectively has led you into trying to communicate exhaustively. Not everyone has the same capacity to digest large blocks of information and assimilate them as you may have. You are estranging people.

I would suggest that you take your approach back to first principles and look at what constitutes effective communication. You may think that highly technical documents should be appropriate for your audience, but the evidence that it isn't is the response you are getting.

Effective communication in this context probably means cutting out all the things that are fascinating, provide background, correct people for using punctuation that you think wrong... all the things that a tutors of my partner in his university days called:

True but trivial

In terms of the emails you are laboriously constructing, all of these things are obstructions to effective communication, they mess up the noise to signal ratio.

Use your detail and fact focused nature to write yourself a solution to writing overlong emails. Analyse the problem, identify the pitfalls, punctuate it correctly, add a ToC. Sigh sadly and shake your head at the limitations of your colleagues and go forth and communicate with them in their own language!

Answer 3

Information is valuable, and I can certainly understand the desire to give the people you correspond with, all the important details you think they need. But let me ask, How many times in your emails have gone over the steps for X, and the steps for Y. Sure, one needs to do both X and Y to accomplish Z.. but if your email is particularly about Z, mentioning X and Y may be helpful, or it may, as you have found, be harmful, depending on the recipients level of knowledge/need/interest.

If your technology job was anything like mine, I would suggest you simply create a set of Standard-operating-documents, and store them someplace where the people that you email, can look at them. Google's DRIVE, for example, would probably work well for this. In there, thoroughly document X and Y, and label the file names clearly.

Now, in your email about Z, rather than a table of contents, you can just include a list of relevant links to the appropriate X and Y documents, at the bottom of your email, in a section called "related information" or something similar. You can even reference these docs from within the email text, if necessary, to describe how they relate to Z.

Now, a simple link can either be clicked-on or NOT by the recipient. The main difference here, is that it is their choice whether or not to look at (or even just "see") the additional info.

You can follow the same linking-to-other-docs procedure when creating the standard-docs themselves. It will prove more flexible to have lots of short docs, with many "related" links, than just a few long ones.

Another advantage of this method is that is reduces your total workload- you only need to explain the details of X once, ever.

Answer 4

I deal with this on a daily basis, because I am someone who loves to write 10 paragraph essays and post them on Facebook or send them as email. I am aware that my approach is not effective.

You mention one thing which resonated with me:

Most of the reason for the long-windedness is an effort to be thorough, reduce known/possible miscommunications

When it comes to technical content, I find there are two paths. One is the giant wall of text that we both love (which nobody ever reads). The other is to insert yourself, saying something like "if you have any questions, do not hesitate to email me about them." Communications is not fire-and-forget.

The mistake both of us make is the belief that the sending of the content is the important part of the communication. As long as the information was written out in text, we consider the job completed properly. However, in reality, it's the receiving of the content that matters, not the sending. That involves their mind, not just yours. The important part of this is that no email will ever fully transmit the knowledge in your mind, no matter how trivial it may seem. Take advantage of that. Leverage it. Give yourself some breathing room to focus on what different kinds of people want to hear.

Focus on one viewpoint which you believe should matter to them, and talk to it. Don't try to give all the viewpoints and get rid of all of the ambiguity. Ambiguity is fine. Give them one tiny viewport into the world you think matters.

Quite often technical content in our minds looks like this:

Do you feel your blood pressure rising, with a need to describe every little detail because the watch just doesn't work without them? Imagine having to read a description of this watch when you really didn't want to.

What you wanted was this:

And the comments section is always open if you have any questions.

Answer 5

I read through your question, and said to myself: I have no clue what problem he describes, but this is surely a wall of text ...

Assuming that this question is representative of your usual communication style, what is good and bad about it?

The main problem is one of focus. I mean, in inquiring about your communication style, you thought it necessary to include

• that most people in your audience are not very "technical"
• that most people in your audience don't know keyboard shortcuts,
• that word can auto-generate a table of contents,
• that you have seen people use slashes and commas incorrectly,
• that bold font should be used for emphasis rather than "air quotes"
• ...

How is that relevant to the way you write your emails? Moreover, I can assure you that people either know these things, or don't care.

How to write better

• focus on the matter at hand, don't allow your mind to start wandering (or edit out unrelated stuff before sending)
• only include stuff that is known to be relevant. Things that may be relevant belong in separate, clearly labeled sections / documents, so people can read them only when they need to
• be clear in what you write, and use the language of your audience. If necessary, extend this language by introducing new terms with clear, unambiguous definitions.

Answer 6

You summarised your question excellently in the title, by the way.

I can relate. Even here I've written paragraphs upon paragraphs before being able to distil it into the essential message.

Find out more, manage their expectations, don't over-commit, and avoid going on tangents.

Here are examples of openers:

• I need more information to pin down the exact issue. What OS are you using? The steps required differ depending on that.
• What have you tried so far?
• This is rather complex. Are you sure you want to go down this route?
• You will need to do [summary], then [summary]. I can explain more if needed.
• You will need to do [summary], then [summary]. Be careful not to [summary] as that could wreck everything.
• When you have a moment please call me and I'll walk you through it.
• Here's a couple of links to articles. Let me know if you need anything else.
• I'm writing a how-to as a lot of people get caught up on this. Will update you when it's done.

As a last resort:

• When do you need this by? It's pretty involved and will require an in-depth response. Expect a long email.