Why does writing matter in remote work?(timcasasola.com)
timcasasola.com
Why does writing matter in remote work?
http://www.timcasasola.com/blog/writing
85 comments
The military has also been responsible for some rather gruesome crimes against the written word [0]:
> 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...
> 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...
Every time you see specs like that, imagine the situation that led to those specs.
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.
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.
That’s funny, but it has me wondering what recipes typically look like for mass produced food.
Having spent some time working fast food many years ago, it’s not far from that. Temperatures, cooking times, sizes. All precise. Much of the food comes from suppliers in a ready to use state — onions, pickles, fries, etc. I would bet that the specifications given to those suppliers are written in similar language.
When i buy fast food I'm chasing memories of my first bites, my first time made enough of an impression that I want to come back.
If you mass produce food then it makes sense to distill the exact notes on what made me spend a dollar the first time so you can have it a second.
There's nothing worse than being out field and getting a spoiled ration.
Not sure I see the problem?
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.
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.
> 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."
That's 0.5 inch. DoD is all metric.
That's 0.5 inch. DoD is all metric.
The army’s field manual for writing. It’s quite good and I find myself referring to it even now, after my military career.
I work with many people who are against writing; they never write anything and they only want to do sync meetings (phone/in person); I am on the tech team usually which makes that even more painful as 'talking through tech' is a horrible thing. Nothing sticks as everyone needs time to think about things.
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!'.
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!'.
After a sync meeting, I find that it can be useful to note down your key takeaways in an email sent to the other party for confirmation. ("For posterity, this is what we just discussed: ...".)
That's called Minutes[1] and is super helpful to have.
[1]: https://en.wikipedia.org/wiki/Minutes
[1]: https://en.wikipedia.org/wiki/Minutes
Can't be, these are meetings at disruptive tech innovators! /s
Ah, I'm not a native speaker, but I'd always thought minutes are what the notes a meeting's scribe takes during the meeting. Thanks for the correction.
Unfortunately, it's not as common to have meeting scribes as it once was. If a project manager exists for the project, then (s)he takes them. Absent a project manager, people take notes individually, which is not ideal.
One of the most useful habits ever.
Writing minutes is useful but has its limitations.
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.
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.
Yep, seen it all... However for me personally the most effective is just doing my own notes and storing those with the meetings etc. If people want to frustrate things then they always can but this seems to be the safest way to protect yourself and your colleagues.
You've made a cardinal mistake of not sharing the minutes right after the meeting or, even better, as a last point of the meeting itself. Would that happen, you could reply: "Well, this is what you saw and accepted before."
I think I didn't write it clear enough:
He was well informed and acknowledged as much, he just still tried to twist it around to a situation where he was right.
He was well informed and acknowledged as much, he just still tried to twist it around to a situation where he was right.
> 'but we did not discuss that!'
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.
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.
Also known as time sink meetings.
For most companies, the process is not the product. Having immaculate meeting notes from sync meetings 3 years ago doesn't keep the lights on.
Preventing the same discussion from taking place again and again and again does help keep the lights on though, and putting things in writing helps with that.
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.
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.
OP mentioned he's in a business owner role. He's probably talking to customers often, possibly scoping projects or features.
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.
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.
When I was a consultant/analyst, we had a few otherwise wonderful clients who were also masters of expanding the scope of projects if you let them. This, more than anything else, taught me the value of clearly documenting deliverables and milestones. That's not to say we couldn't make adjustments if needed but doing so needed to be done as a formal mutually agreed-to process.
Sorry no - I work on enterprise websites for a very big brand and the process is a key part of the product - liaising with European developers creative agencies in the UK / US and the brand and ourselves is a key part.
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)
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)
> For most companies, the process is not the product.
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.
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.
Whenever you compose an email, put your ask in the first sentence. Do you want information from them? Do you want them to do something for you? Put it in the first sentence. Then put the explanation and details in the rest of the email.
One of the depressing things I notice as I get older is that no-one reads anything. If it's not in the first sentence (or, for some people, last sentence) it is ignored. So I write 1 line emails. It's on HN too ofcourse; people respond to the first sentence without reading the rest, missing every and all nuance. Great stuff.
Yup, that's the downside of modern day internet culture; even as a software developer, my main and most used skills are reading and writing. And with reading, since there's so much of it people end up skim reading / skipping.
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.
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.
Also, at least if you're writing it to me, don't write several rambling pages where you also disparage other people in the project and then ask me at the very end of the email to not share it with the group.
Put that don't share request at the top in caps, bold.
Sorry, still sore years later.
Put that don't share request at the top in caps, bold.
Sorry, still sore years later.
Oof. Yeah, complaints about other people - if they are NOT formal - should not be in writing in the first place.
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.
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 followed this format ever since I read about BLUF [0], and I’ve found it to be highly effective.
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...
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...
Miltary parlance does not always translate well to civilian. His first example email
~~~
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.
~~~
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.
Yes, this seems like it’ll cause resentment and arguing unless Shannon is already bought in. She reads the first line and maybe thinks “but why? I don’t like it!”. She only gets to the reasoning after she’s set against the decision and looking for reasons to disagree. The other way round, she reads about increasing team morale and thinks “oh, good, I agree”, then is more likely to agree with the decision.
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.
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.
But couldn't this be improved by just adding the 'condensed version' of the reason in the bottom line? For example:
'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.'
'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.'
I would have put that the other way round
" 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."
" 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."
I’m exclusively talking about the suggested structure. The tone of the communication is up you. That said, if you have instructions to give somebody, it’s probably best to make sure there isn’t any ambiguity about it.
This.
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
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
"hey, how are you" in he middle of an email after a request is very strange. Asking for something and finishing with the non committal "let's get together soon" is also a red flag that you might want something from me from a business perspective but are only feigning interesting from a personal perspective.
That reads really weird. Putting a greeting in the middle of an email is jarring.
I disagree with this but it may just be a style thing. Reading "Hey, how are you?" in the middle of the content put me on guard, I feel like I might be being manipulated somehow.
This sounds very transactional, the personal concern seems to be an aftertoghth.
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.
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.
I really rail against people who think 'This.' is a sentence, let alone a useful contribution.
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.'
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.'
Sometimes. Good 'ol BCQ works just fine as well when done succinctly.
I absolutely love async communication. I’ll look for writing competency when interviewing at my next job. I’m bogged down in meetings enough as is. Phrases like “hey let’s talk voice” is abused heavily.
I’ve been to meetings where the topic was to discuss what to do in our next meeting. Absurd.
I’ve been to meetings where the topic was to discuss what to do in our next meeting. Absurd.
I agree. First thing that comes to mind though is that you need the other person to have a certain level of competence, writing and reading skills, and dedicated time in order for written communication to work. If any of those things break down, you might be more successful with voice chat or phone calls.
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.
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.
In my new job I do a lot of writing; documentation, architecture (ADR's), and lots of details in the user stories themselves - although those are mainly for myself.
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?
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?
> What if they start reading it but just glaze over because of the sheer volume of it?
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)
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)
> But I have a fear. What if nobody bothers to read it?
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.
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.
I think the trick is to write in a way that gets other people to read it, and in a way that's cognisant of the fact that that reading will be more akin to skimming. Gratuitous use of bullet points and bolding two or three key takeaways are the main quick hacks I use to in support of that goal.
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.
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.
Exactly. When I summarized a complex technical issue to a mixed audience, the TLDR version was in nested bulleted format, each line limited to ~5 words. Higher level bullet points were targeted at non technical readers and sub points aimed at the techie ones. Non technicals can opt not to dig further into sub points.
Some notes:
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.
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.
I have three replies, in no particular order.
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.
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.
> In this meeting, I proceed to read them the contents of my email, sometimes literally and sometimes paraphrasing.
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)
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 not a bad idea. I think, though, that the problem was that these people didn't really understand what we were doing, so needed hand holding.
Can anyone recommend a writing coach I could work with?
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.
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.
I am not offering to do this for you, but I have absolutely wondered MANY times over the years if this -- coaching highly technical people on writing better -- was a business model.
I don't know what you mean by "business model." Certainly there are lots of people who do music lessons, presentation skills, tutoring, etc. as either a part-time thing or as a full-time business. If it's 1:1 instruction, it's not all that scalable although the seemingly more successful examples I've seen do things like classes for companies and individual sessions for executives.
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 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.
While no doubt I'm uninformed, my sense is professional development at the one-to-one or one-to-few level is geared towards exec levels, such as exec coaching and management training.
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.
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.
No I think that's quite accurate. When I've had e.g. presentation skills training at work, it's been a (small) group thing. Though I could probably get 1:1 professional coaching for things if I asked for it as part of professional development.
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?
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?
I'd guess it'd be similar to other consulting where you have different offerings and price points: 1:1 coaching, tuition groups, self-serve classes. Personally I'd like to make use of the first one and expect to pay a premium for it.
My hypothesis is technical writing is different from non-technical writing and those who have mastered both the skills are in huge demand and have better career path than being a coach.
Probably also true. I'm sure I make more in my current role than I would coaching people, unless I was able to either leverage that into some sort of weird social media/Youtube phenom, or scale it up by hiring other people (and then you just end up having the professional-services-firm problem).
I think this is a 2-way street, as with all things.
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.
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.
I love writing, but I regularly work with people who don't. Just wondering if folks here have any tips for dealing with:
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?")
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?")
After years and years I’ve decided that you are never going to convert either group, no matter how hard you try or what kinds of benefits you extol - they simply don’t “get it”, and that’s ok.
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.
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.
On top of the suggestions in the article, I would wholeheartedly recommend having a look at Steven Pinker's The Sense of Style [1] for a practical guide on writing well.
[1] https://www.goodreads.com/book/show/20821371-the-sense-of-st...
[1] https://www.goodreads.com/book/show/20821371-the-sense-of-st...
[deleted]
* Keep it simple.
* 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.
* 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.
Any text longer than 3 lines must go through multiple edits. This rule must be applied to all forms of textual communication including slack or teams chat.
PS: I would be thankful if you can make my post succinct without any loss in the information.
PS: I would be thankful if you can make my post succinct without any loss in the information.
Did anyone else have to read that headline multiple times in order for their brain to parse it?
I have strong convictions about business communication.
Efficiency is key.
Every character is one brain processing unit.
Time is all we have.
Agreed.
Efficiency is key.
Every character is one brain processing unit.
Time is all we have.
Agreed.
This piece is kind of fluffy, I don't see why it's on the front page. Not particularly insightful.
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.
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.
> From my experience, Filipino's speaking English
Hey there - this seems like unnecessary ethnic stereotyping.
Also, no apostrophe is used in this situation.
Hey there - this seems like unnecessary ethnic stereotyping.
Also, no apostrophe is used in this situation.
You're quoting out of context. The full quote was Filipinos who speak English as a second language. It's reasonable to point out that they'll (ESL's) need more help in getting up to speed with communication which may include fluent speakers.
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.
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.
[deleted]
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...
[2] https://en.wikipedia.org/wiki/Five_paragraph_order