Why does writing matter in remote work?
timcasasola.com
timcasasola.com
The military takes writing seriously.[1] People write things which are acted upon by others. The reader needs to understand clearly what is intended. Especially when they are out of communication with the sender.
It's worth understanding the military five-paragraph order format.[2] Not because it's used much in civilian life, but because it's a checklist for what must be covered in an order. Note especially "Commander's Intent" and "Desired Endstate". A key point in combat orders is knowing why something is being done. Because the enemy gets a vote. If things don't go as planned, then what?
[1] http://tsg3.us/tnsg_lib/pldc_school/wobc/is_1460_materials/c...
> Vanilla flavoring shall be pure or artificial vanilla in such quantities that its presence shall be organoleptically detected, but not to a pronounced degree.
> Candied cherries shall be made from pitted cherries. They shall be thoroughly processed with sugars to a soluble solids content of not less than 72 percent and artificially colored with a red dye. They shall be cut to yield 1/4- to 1/2-inch (6.4 to 12.88 mm.) cherry pieces on the average.
> One of the changes dictated by the Defense Department, Nunn said, shifts "the tolerance of candied cherries from 12.8 mm. to 12.7 mm. Always onward and upward."
> The flavor of the finished product shall be typical of the type indicated. There shall be no off-flavors or off- odors.
In case you haven't caught on, this spec is describing a fucking fruitcake.
[0] https://www.chicagotribune.com/news/ct-xpm-1985-12-25-850329...
I'm bet at some point the candied cherries being used were too small (e.g. a supplier dumping their leftovers) and so they had to get specific about the requirement.
It is very detailed, but isn't that the point of a spec? The alternative is getting/accepting a low bid where the vendor puts in a homeopathic dose of vanilla and one lousy cherry, resulting big profits for them but a deliverable that's almost entirely but not quite, unlike fruitcake.
You could imagine a different system, where somebody tastes existing fruitcakes from different bakers, then picks one that seems like a good value for the money. However, there is still the problem of ensuring that the delivered product matches the sample.
Moreover, it could, in theory) allow for corruption--how do you know the taster and baker aren't colluding? The US (and especially DoD) are set up to avoid that sort of "individual corruption", at the expense of much more bureaucracy. This isn't totally successful--somebody will instead lobby to reduce the maximum cherry size to 1/3 inch to exclude a competitor--but at least it's an ethos.
That's 0.5 inch. DoD is all metric.
Inevitably, after a while, you get people losing track of things that were actually said, that were actually agreed on etc because there are no documents or that kind of tracking for that matter (there is stuff in Jira, but that's only following the hard tech points, not all the rest that was also discussed).
My business partner and me write a lot but we know nobody is going to read it; we do it anyway because I don't want to end up with a feeling of insanity in yet another phone call with 'but we did not discuss that!'.
In these cases, having notes will prevent scope creep and will be necessary to have customers accept the work. Customers will forget what was discussed and what was agreed to. They will want to add that "one last thing" just when you're expecting to close the project.
Even in different roles (or internally), I think many would benefit from writing down meeting notes because it anchors the discussion and creates shared understanding. Voice only will cause many to forget specifics or move the goal.
I don't think OP is in favor of writing a book for every meeting. Having notes / documentation will make you more effective. It will also lower the frequency of you and the other party having different expectations. It's a good habit to have for these reasons and the many others outlined in this thread.
Unfortunately a lot of the big name consultancies and agencies are terrible at written communications and quite often farm out work to what appears to be interns with poor writing skills and very little knowledge of the web.
I got sent a scrappy unformatted PDF yesterday that if I had delivered that when I worked for British Telecom would have got my appraisal marked as needs improvement (the first step to a PIP)
As does having the original reasoning for why things were done the way they were three years ago, when there's a new feature request and nobody is left of the original team.
Where do you think the product comes from? A bunch of people randomly doing whatever they want? The process absolutely impacts the product. Does SCM keep the lights on? It's the same thing, except for code.
I've been fighting the flip side of that coin in my team - people who make an idle comment on a phone call, and come back at you months down the line with, "This was already discussed and decided in earlier meetings."
It is possibly the most frustrating thing about my job these days, so I'm hoping as more people get used to working remotely, writing will start to take precedence.
A few years ago I worked with two technically brilliant but somewhat unpleasant guys.
After a while I realized it was a good idea to write down everything so I made sure I coukd always point to a mail or something.
Turned out even that had its limitations. At one point we discussed something and I ponted the older one of them to a mail where I had described it. His answer:
Sure, that's what you wrote but not what you meant.
I left not too many moons later.
He was well informed and acknowledged as much, he just still tried to twist it around to a situation where he was right.
Even if you are emailing an old friend for a favor, put your request up front then put the cordial stuff after, its much more sincere that way.
> Joe, we are looking for advisors to sit on our board. This is a non-paying position so I'm emailing all my old friends and asking for favors. Hey, how are you? How is your wife and son? Either way lets get together soon! --Aaron
It's especially galling when the topic is 'Put your question / point in the first sentence / paragraph' and someone's first word, sentence, and paragraph is simply 'This.'
I was struggling with this dilemma recently, when wrting an email. Knowing what you just said, that your request should be in the first paragraph, and at the same time wanting to show humman connection, I don't think that I did very good job. Still haven't found a smooth way to express both things in the first sentance/paragraph.
I guess, it depends on the person you are writing to.
Also referred to as SCQA. Situation, Complication, Questions, Answers.
I don’t use the same subject keywords the article describes, but I try to keep it concise. I put the point of the email first, a bit of background, and further explanation below that if required. I don’t think anybody really appreciates the beating around the bush and story telling that goes into a lot of corporate emails.
[0]: https://hbr.org/2016/11/how-to-write-email-with-military-pre...
~~~
Shannon,
Bottom Line: We will reduce the number of days that employees can work from home from three to one day per week effective December 1st.
Background:
* This is an effort to encourage team morale and foster team collaboration
* All members of the management committee supported this decision
~~~~
A lot of people would take that for what it is, orders and not like it at all. In the military diplomacy is not so strongly needed as there is a clear chain of command. Things are not so set in the corporate world.
If the boss can tell Shannon to deal with it like in the army, no problem. But in an office Shannon has lots of coworkers and bosses to formally complain to! Giving bottom lines which are in any way controversial in this manner will probably backfire imo.
'To improve team morale, we will reduce the number of days that employees can work from home from three to one day per week effective December 1st.'
" In order to encourage team morale and foster team collaboration, the management committee have decided to reduce the number of days that employees can work from home from three to one day per week effective December 1st."
Once upon a time I was on an internet forum and I would read each and every post. Nowadays, if it's longer than a paragraph long and not by someone I care about, I just glaze over - I can't be bothered anymore. Mind you, having less time for that kinda thing also doesn't help.
Put that don't share request at the top in caps, bold.
Sorry, still sore years later.
If you're making a formal complaint, by all means. But otherwise, treat it like you're posting it on the internet for everyone to see.
I’ve been to meetings where the topic was to discuss what to do in our next meeting. Absurd.
For example, I have worked with clients or bosses who unfortunately were unable or unwilling to handle written communication effectively. Different types of problems can occur. Some people may be busy and decide they don't have time to acknowledge emails. So you literally don't know if they even read them. The next issue is they will read the first one or two sentences and get the gist, but are unwilling or unable to do any real thinking about what you wrote, and so will reply with something fairly obvious that may actually have been covered in your email. So technically they read it, but they didn't understand it well or do any analysis of the information.
The other one is where the other guy has a different viewpoint and that causes them to not want to understand the part of your message that contradicts it.
The other issue that can occur is that some people just don't quite have enough will power or cognitive ability to focus on something without having an audio chat. So something that requires their input but isn't their own task, they are not able to put adequate analysis into it in an email, even though you can see they are trying. Sometimes they are a manager and can't really operate well without a meeting or oral discussion of some kind.
Having said all of that, I prefer working with people that can work asynchronously on a project.
But I have a fear. What if nobody bothers to read it? What if they start reading it but just glaze over because of the sheer volume of it? I mean the ADR's for example are a lot of 'internal' musings that I've considered.
I am a solo developer on this project at the moment (my colleagues do other stuff), so I've got nobody to check my work either.
At my last job, my colleague just said to not bother (we were err, very different personalities in that regard), it's wasted effort, I'm not going to bother reading it, just show me how to start it then show me the code. Which I guess works in smaller codebases in easier domains, but this won't be one of those.
Is there a similar article that emphasizes that people should read other people's writings?
Longer-form writing and proper prose are more useful for e.g. tutorials, but things like user stories or other reference material should really be written to be skimmable, in my opinion.
I'd generally try to disregard the fear that your docs won't be used. At worst, they'll allow people to determine the original design intent and reconstruct how and why the project diverged at some point after you stop working on it. As long as the docs are part of the version control scheme for the project, you should be fine. If you however are using "share drive version control" aka a bunch of copies of the documentation for each release on a network drive separate decoupled from the project, it might as well not exist. If that's the case, you need to get it in version control. Sorry that was a bit of a tangent but I had flashbacks to a previous project.
If you want people to read the documentation, make it concise. The ADRs can be verbose and logged as necessary. That's kinda the point of an ADR. They record the mindset and intent of the developer. Everything else however needs to be easy to jump into. Have a super concise summary that links to subtopics and put in the detail there.
If you want people to maintain the documentation, integrate it into the build system/CI. If you have code examples in your documentation, they need to be unit tested so that the build system will warn you when the docs are out of date. Another avenue is to associate documentation with source code so that merge checks require documentation associated with modified sections of code must be checked off before commit. Getting this right is definitely the hardest part with documentation but when done well, it is immediately evident.
Also I know I have seen articles like you mentioned but for the life of me I can't find them. If you come across them, I'd love if you could share some so that I can bookmark them.
This is definitely a big problem, especially in cases when reporting up the chain of command or sideways (to colleagues or other teams).
People don't read.
A big part of the reason seems to be the low expectation of value from any text. Since most writing is not well organized and rambly, people just assume it's not worth reading. And to be honest, they would be right most of the time... except when they are not.
The problem is the well thought out email that summarizes all the info about the project from past meetings that took a day to prepare, contains all the important links to documents, and describes a well thought out strategy for next steps will get just as much attention as the average non-consequential email of the same length.
Sometimes I think we need to have color coding for the hours that went into writing a piece of text, e.g. a paragraph showing in dark font indicates many hours and synthesis went into producing it (including decisions, consultations, planning, feasibility, etc), vs. a light gray text that is just a random suggestion. Such a color coding might help signal to the non-reader crowd (most people) that something is worth reading... something like nutritional facts.
Write concisely and in order of importance. The Inverted Pyramid model [1] is helpful. Key points answering questions Why, What, When, How, Where go up front. Then, important details. Finally, internal musings and background info go to the bottom. This way, the reader can stop at any time and they won't miss anything crucial.
Another important tip is to refine the documents you've already written. Think of it as refactoring. Rewerite unclear, long sentences. Be consistent in describing the same procedures. Delete parts that aren't necessary anymore.
Just like maintating the old code, it takes time and may seem as a waste of efforts. But it's well worth it.
> I've got nobody to check my work either.
Are there any other stakeholders that may be interested in what you're doing? Interns? Vendors? Ideally, your documents should be written so anyone can understand the main points and follow them. They don't have to gork the gory details and that's fine. Ask your collegues anyway, even if it's a first few paragraphs.
[1] - https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)
Fewer commas, surely.
1:
> We document projects in Notion. We send meeting invites with a written description of the purpose.
Hah! I can't remember the last time I saw well-maintained collaborative documentation at a client. And I am among a small handful of people I know who provide descriptions of meeting invites.
2:
I looooove written communication with others who are competent. I have an unfortunate history of colleagues who will immediately ask for a meeting whenever I send an email with more than one short paragraph or with an attachment containing text of interest. In this meeting, I proceed to read them the contents of my email, sometimes literally and sometimes paraphrasing.
I have narrowed this to the coworkers by exasperatedly sharing said emails with coworkers and with friends in different fields to see if they understand them. The number of these experiences is much higher than the number of meeting invites I have received with well-written descriptions included.
3:
Yes! I agree with all of the points this author is making.
Did you try sending them voice messages instead, possibly via some TTS service?
(originally intended as joke, but now that I think about it... - especially since I sometimes use a STT service for voice messages I receive)
It's important to my role. I'd happily pay someone to set me (and hold me accountable to) relevant assignments and give feedback on my work.
I understand there are writing courses, it's the 1:1 timely feedback I'm seeking.
For individuals though, I think it's easy to see that the hourly rate can't be all that high.
For writing, the best bet is probably to get hooked up with some editor who does this on the side or maybe a writing prof at a local community college or adult education center.
For my part, I'm not exec level yet am in a position to use either disposable income or company money on coaching for skills such as writing.
My first thought too was looking for journalists/editors/local university lecturers who may be looking for some extra work. I'd guess that'd require trial and error for both parties.
My first choice would probably be to try to find an editor who does or would do this sort of thing as a side-gig. Maybe you have co-workers who have worked with one of the tech publishers like O'Reilly or Apress in the past who could do an introduction?
Written communications have tremendous advantage in that you can take an unlimited amount of time to document intricate structures and processes in such a way that they could be consumed easily by other parties. But, writing takes a lot of time in order to achieve the highest value and can sometimes become a bottleneck.
Verbal communications are useful in those cases where the written communications have faltered in their ability to convey meaning, and also in cases where you need to quickly iterate through a dynamic situation. But, verbal communications are prone to rambling and argumentative paths which begin to reverse business value.
IMO, the best is a dual-stack approach. Have a daily standup call, but require that everyone email out to the participants all of their discussion points prior to the call. All participants should be expected to read the discussion points of others prior to joining the call. This means that everyone should be more-or-less discussing just the aspects of the written communications that have gaps or otherwise raised new concerns. I find this can eliminate most of the frustration that can emerge with both techniques. For us, this isnt even an explicit email process. We just have a special label in Github we apply to those issues which we'd like to review each morning. Over the course of each day, written communications in these issues would determine if a subsequent review is required.
1. Non-native English speakers for whom writing in English is more cumbersome than talking -- so sync meetings are preferred
2. Native English speakers who aren't written word/visual people and who vastly prefer a phone call (e.g. extroverts, sales folks, folks who reply to emails with "why don't we jump on call?")
The only solution I have found is to carefully evaluate every situation.
If it’s important that you get a timely answer, sometimes it’s worth jumping on a call, even if you think a quick Slack message or email would be the best for both parties. For group 1 that may be because they’ll lock up and pause trying to figure out how to respond (in many cases because they’re trying to make sure everything is perfect and 100% - you’d be self conscious about your Russian, wouldn’t you?) and for group 2 that may be because their only break is in the car on the way from one client to another. This is the same “do I want to die on this hill?” part you have with any interpersonal disagreement.
Second, it’s helpful to carve out specific times when this kind of “jump on a call” can happen. Particularly with remote workers on different time zones, it may not always be practical for everyone to jump on a call - for instance I’m at dinner with the wife and can spend 30 seconds answering a Slack message while she’s in the restroom, but I’m not getting out my headset and getting on a call. I discourage setting up a recurring call, because then you run into the issue of people holding things until the meeting that could and should have been dealt with in a different manner, but specifying that “between two and four every day” are available for calls can help with the sense of urgency for the other party. If it’s 5 already and they know you can’t get on a call, perhaps they’ll decide a textual message is worth the effort.
Establishing the time periods also helps with “quiet hours” where you can turn off message notifications and really focus. The key is that everyone needs to coordinate to establish those periods and they need to be known, otherwise it’s just frustrating to never be able to get ahold of anyone.
[1] https://www.goodreads.com/book/show/20821371-the-sense-of-st...
* When possible ask questions that can be answered yes or no.
* One question per email. My experience is that multiple questions in an email are rarely answered in full.
* Use simple words. Many people you work with, or write for, have English as a second language.
* Don't use "it" in a sentence. Replace "it" with the noun you're referring to.
PS: I would be thankful if you can make my post succinct without any loss in the information.
Efficiency is key.
Every character is one brain processing unit.
Time is all we have.
Agreed.
From my experience, Filipino's speaking English as a second language generally have difficulty fitting in with Western culture when working remotely. This requires extra communication and emphasis on expectations to get everyone on the same sheet of music. Clearer explanations are required than with native English speakers.
One example in the text. The OP misinterprets the Basecamp message that 5 people in a room for an hour is a 5 hour meeting rather than a 1 hour meeting.
> Had the Meeting Organizer took notes from the Very Important Meeting, three hours would be saved.
No, it's a 5 hour meeting because there are 5 people in the room. If you have a billable project which 5 people each put an hour into, you bill 5 hours for that project.
Writing for communication is different than writing documentation. Communication centered around meetings is different than asynchronous communication. The OP is bundling all these things together in one post.
A good portion of the article is on how to write well. This is how you write an essay, not how you talk to people.
My two quick points shooting from the hip...
1. Every group you need to collaborate with is different. By "group" I'm including situations where the group might just be a single boss or client. Your job is to adjust to the communication style of that group. Some groups like to communicate in fragmented "texting" speech. Some groups communicate in perfect English. Best to adjust or you won't get much further than that.
2. Be authentic. Write like you speak. Start out speaking like you would to any person you might encounter in public. Then you can adjust based on the group. If you're trying to appear as someone you aren't, people will see through you quickly and you'll look silly. It's also refreshing to be speaking to regular people. If you have deficiencies, let them out so that people can help.
Hey there - this seems like unnecessary ethnic stereotyping.
Also, no apostrophe is used in this situation.
Further context is the origin of the author. The author appears to be Filipino. The author specifically mentioned a scenario of a meeting between someone in London (most likely a fluent English speaker), San Francisco (most likely a fluent English speaker) and Manila (most likely ESL.) Why not point out the other difficulties of this scenario? I live in the Philippines, so I experience this regularly.