5 ms·

> it doesn't matter if you have a blog article recommending structured emails over video calls Exactly! Funny thing is that if you send these people an article

> it doesn't matter if you have a blog article recommending structured emails over video calls Exactly! Funny thing is that if you send these people an article explaining the benefits of written docs (design docs, RFCs, proposals, any text document documenting a decision), they will just simply not read it. I'm on a team where I believe we started gigantic refactoring and redesigning projects without being clear on the goals, non-goals, and tradeoffs we take. I proposed that before we start working on something huge, we should write a short document where we explain what, how and why we want to do. I recommended them some articles, for example "Design Docs at Google" [1], and "Scaling Engineering Teams via RFCs: Writing Things Down" by Gergely Orosz [2], but I couldn't even convince them to read those articles... I didn't even send them my favorite posts about the Amazon 6-page memo, because I knew they'd dismiss the whole idea in a second (no matter if I told them that we could do "OurCompany 1-page memo"). This lead me to the sad realization, that our team will never start "writing things down". In my opinion, it would force us to think things through, but it seems like they disagree, or they just don't care. My coworkers will not even read a 3-paragraph ticket, but they'd love to talk about the same ticket for an hour in a video call. Then in 3 weeks, nobody remembers anything anyway, and they discuss it again. [1] https://www.industrialempathy.com/posts/design-docs-at-google/ https://www.industrialempathy.com/posts/design-docs-at-googl... [2] https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/ https://blog.pragmaticengineer.com/scaling-engineering-teams...

darkerside 5y ago
You want to convince them, but you won't meet them on their terms to do so? Maybe you should try having a conversation with them about it instead. Actually, a series of conversations. And be patient because influencing other people's base assumptions takes time. Put yourself in their shoes, they want you to understand the benefits of in person communication, so they schedule meeting after meeting with you to talk about it. You are immediately fed up because you actually do already understand the benefits, and all these meetings are a waste of time. Wouldn't you rather they demonstrate that they understand your point of view by writing up a document, or sharing an article, describing the benefits of in person communication that you could consider on your own time? I'll also say, one of the big benefits of in person communication is getting real time feedback on body language and tone which tell you how the other person feels about what you are saying. If that's not something you care to do in this instance, when it's so important for you to gauge their opinions on it, is it any surprise that they think even more written communication will only put the team even more out of sync?
- blowski 5y ago
  This, I think, is at the root of the good and bad of written conversation. At its best, it allows the author to articulate their thoughts and share it widely for readers to consume and archive efficiently. At its worst, the author writes an unreadable polemic without any thought of the audience. To the writer, their point is clear, obvious, and unarguable. To the reader, it’s a muddled, angry rant. The readers then type their own polemics in response, disingenuously cherry-picking and taking phrases out of context. And on it goes. Not all written conversations look like this, but a lot do.
- serial_dev 5y ago
  Thank you for your note, I'll keep it mind in case I try to get them to document things and / or read things. The goal of my comment wasn't to document every attempt I made in the last months to convince them that writing some things down would be beneficial for the team. I do speak with them, we have video calls and we also talked about this topic multiple times. I wanted to point out that it's a funny experience when you send a document to someone with the purpose of providing them a great overview, highlighting the benefits of these design docs... And nobody reads them. I already understand the benefits of in person communication, I don't want to eradicate video calls, I'd just prefer to write our decisions down so that other people who were not part of a decision can read these docs and join later. In the end, I understand that I'm trying to change the status quo and change the team culture, I know it's a hard thing to do, and I get it that it will take a while.
  - darkerside 5y ago
    Fair point, I'm sure there's a lot you are doing that didn't fit in the little white text box. Good luck!
- otabdeveloper4 5y ago
  > they want you to understand the benefits of in person communication I doubt that. Mostly they just want to punt responsibility. (I've been in these shoes many times.) A written record trail means the buck eventually stops somewhere. Talking it through without writing it down means you have plausible deniability.
Aeolun 5y ago
Oh! We work in the same place! Or at least close enough that it doesn’t matter what the actual name is.
commandlinefan 5y ago
> I recommended them some articles I have a slightly cynical take on why most programmers don’t read much: you can’t log “reading” into a time tracking system that has to add up to (at least) 40 hours a week.
- Aeolun 5y ago
  You can log it under ‘working on project xxx’? Literally all my time regardless of what I do goes under there. I guess it makes a difference for consultants, but they can log it under unbillable ‘administrative actions’ if the very necessary ‘continuous education’ does not exist.
sul_tasto 5y ago
If you have time could you reference your favorite posts on the Amazon 6 page memo?
- sulZ 5y ago
  I found this article on it: https://writingcooperative.com/the-anatomy-of-an-amazon-6-pager-fc79f31a41c9 https://writingcooperative.com/the-anatomy-of-an-amazon-6-pa...
jbverschoor 5y ago
Because most documents are not written to be read. The are written to have something published. Ego, status, whatever. Similar to over architecting. Spend more time making things more concise, and people will read. Evidence: tiktok and other shorts
upofadown 5y ago
Everyone that works in development is literate but not everyone that works in development has good reading comprehension or is good at generating meaningful prose at a keyboard. Many people who work in development just don't like to read and consider it a chore. I think an interesting interview question would involve reading. "What were the last 3 things you have read to learn something?" "Do you read for enjoyment?" Based on the results you could group people in terms of how they relate to text.
- ctvo 5y ago
  In my experience a key characteristic of a good software engineer is their ability to handle dense, technical texts. We do it all the time, from academic papers (less often) to documentation (every other hour). Not liking to read (?!), and thinking it's a chore, because we're only humans, will mean you won't do it unless forced and will either lack a deep understanding of a subject or reach for someone else to do it for you (RTFM). Not a fan of the often repeated, flawed [1], "we have different modes of learning" mantra that sometimes comes with these discussions too. That myth is so hard to debunk likely because of this very issue! 1 - https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/ https://www.theatlantic.com/science/archive/2018/04/the-myth...
ChrisMarshallNY 5y ago
I wrote an article (since it's written, I don't expect it to be actually read)[0] , about the importance of not writing too much stuff down (Ironic, I know). I call it "concrete galoshes." The structure can become more important than the project. That said, not having a structure can be absolutely deadly. It's not for the faint of heart. I seldom write down a detailed project plan (I write about that here[1]. Feel free to not read it, as well). Instead, my projects start with what I call a "napkin sketch," and evolve, as they progress. The results can be amazing, but I also end up backtracking a lot, and tossing out a lot of code. I feel that you can't work the way I work, unless you are highly experienced (I've been at it over 30 years). I make big decisions, on the fly, and I need to have a really clear idea of the ramifications of these decisions. Often, the devil is in the details. It's quite possible to decide to do something one way, and get there, and then realize that a corner case makes the design unusable, and/or downright dangerous. I'm not a fan of "design by buzzword." Modern techniques are often marvelous, but they can be unsuitable for some applications. Having a toolbox available, that includes a wide range of options, is invaluable. I am a fan of early, high-quality usable product. One of my techniques, is to leverage Apple’s TestFlight beta service, as early as possible. This allows non-tech stakeholders to have meaningful say in the project. Screenshots and interaction diagrams are fairly useless. They take a lot of time (and expense) to create, and no one reads them. They also tend to add unproductive rigidity to the project. [0] https://littlegreenviper.com/miscellany/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/ [1] https://littlegreenviper.com/miscellany/evolutionary-design-specification/ https://littlegreenviper.com/miscellany/evolutionary-design-...
- ctvo 5y ago
  > I seldom write down a detailed project plan (I write about that here[1]. Feel free to not read it, as well). Instead, my projects start with what I call a "napkin sketch," and evolve, as they progress. The results can be amazing, but I also end up backtracking a lot, and tossing out a lot of code. This is fine for a sketch, a prototype, or an exploration. If you do this to produce production, critical path code, on a professional team with others you're selfish: - The team, not only you, maintains this work that they have no agency over. - You skipped feedback loops, and ignored the expertise of others. - You've removed information sharing and visibility as you go into your cave and come back out with a solution. > I feel that you can't work the way I work, unless you are highly experienced (I've been at it over 30 years). I make big decisions, on the fly, and I need to have a really clear idea of the ramifications of these decisions. Often, the devil is in the details. Yes, the devil is in the details. Get some feedback from other people and stop designing by mistakes I happened to notice and catch. The ones you didn't notice? They're bugs your teammates fix.

darkerside 5y ago

You want to convince them, but you won't meet them on their terms to do so? Maybe you should try having a conversation with them about it instead. Actually, a series of conversations. And be patient because influencing other people's base assumptions takes time. Put yourself in their shoes, they want you to understand the benefits of in person communication, so they schedule meeting after meeting with you to talk about it. You are immediately fed up because you actually do already understand the benefits, and all these meetings are a waste of time. Wouldn't you rather they demonstrate that they understand your point of view by writing up a document, or sharing an article, describing the benefits of in person communication that you could consider on your own time? I'll also say, one of the big benefits of in person communication is getting real time feedback on body language and tone which tell you how the other person feels about what you are saying. If that's not something you care to do in this instance, when it's so important for you to gauge their opinions on it, is it any surprise that they think even more written communication will only put the team even more out of sync?

blowski 5y ago
This, I think, is at the root of the good and bad of written conversation. At its best, it allows the author to articulate their thoughts and share it widely for readers to consume and archive efficiently. At its worst, the author writes an unreadable polemic without any thought of the audience. To the writer, their point is clear, obvious, and unarguable. To the reader, it’s a muddled, angry rant. The readers then type their own polemics in response, disingenuously cherry-picking and taking phrases out of context. And on it goes. Not all written conversations look like this, but a lot do.
serial_dev 5y ago
Thank you for your note, I'll keep it mind in case I try to get them to document things and / or read things. The goal of my comment wasn't to document every attempt I made in the last months to convince them that writing some things down would be beneficial for the team. I do speak with them, we have video calls and we also talked about this topic multiple times. I wanted to point out that it's a funny experience when you send a document to someone with the purpose of providing them a great overview, highlighting the benefits of these design docs... And nobody reads them. I already understand the benefits of in person communication, I don't want to eradicate video calls, I'd just prefer to write our decisions down so that other people who were not part of a decision can read these docs and join later. In the end, I understand that I'm trying to change the status quo and change the team culture, I know it's a hard thing to do, and I get it that it will take a while.
- darkerside 5y ago
  Fair point, I'm sure there's a lot you are doing that didn't fit in the little white text box. Good luck!
otabdeveloper4 5y ago
> they want you to understand the benefits of in person communication I doubt that. Mostly they just want to punt responsibility. (I've been in these shoes many times.) A written record trail means the buck eventually stops somewhere. Talking it through without writing it down means you have plausible deniability.

Aeolun 5y ago

Oh! We work in the same place! Or at least close enough that it doesn’t matter what the actual name is.

commandlinefan 5y ago

> I recommended them some articles I have a slightly cynical take on why most programmers don’t read much: you can’t log “reading” into a time tracking system that has to add up to (at least) 40 hours a week.

Aeolun 5y ago
You can log it under ‘working on project xxx’? Literally all my time regardless of what I do goes under there. I guess it makes a difference for consultants, but they can log it under unbillable ‘administrative actions’ if the very necessary ‘continuous education’ does not exist.

sul_tasto 5y ago

If you have time could you reference your favorite posts on the Amazon 6 page memo?

sulZ 5y ago
I found this article on it: https://writingcooperative.com/the-anatomy-of-an-amazon-6-pager-fc79f31a41c9 https://writingcooperative.com/the-anatomy-of-an-amazon-6-pa...

jbverschoor 5y ago

Because most documents are not written to be read. The are written to have something published. Ego, status, whatever. Similar to over architecting. Spend more time making things more concise, and people will read. Evidence: tiktok and other shorts

upofadown 5y ago

Everyone that works in development is literate but not everyone that works in development has good reading comprehension or is good at generating meaningful prose at a keyboard. Many people who work in development just don't like to read and consider it a chore. I think an interesting interview question would involve reading. "What were the last 3 things you have read to learn something?" "Do you read for enjoyment?" Based on the results you could group people in terms of how they relate to text.

ctvo 5y ago
In my experience a key characteristic of a good software engineer is their ability to handle dense, technical texts. We do it all the time, from academic papers (less often) to documentation (every other hour). Not liking to read (?!), and thinking it's a chore, because we're only humans, will mean you won't do it unless forced and will either lack a deep understanding of a subject or reach for someone else to do it for you (RTFM). Not a fan of the often repeated, flawed [1], "we have different modes of learning" mantra that sometimes comes with these discussions too. That myth is so hard to debunk likely because of this very issue! 1 - https://www.theatlantic.com/science/archive/2018/04/the-myth-of-learning-styles/557687/ https://www.theatlantic.com/science/archive/2018/04/the-myth...

ChrisMarshallNY 5y ago

I wrote an article (since it's written, I don't expect it to be actually read)[0] , about the importance of not writing too much stuff down (Ironic, I know). I call it "concrete galoshes." The structure can become more important than the project. That said, not having a structure can be absolutely deadly. It's not for the faint of heart. I seldom write down a detailed project plan (I write about that here[1]. Feel free to not read it, as well). Instead, my projects start with what I call a "napkin sketch," and evolve, as they progress. The results can be amazing, but I also end up backtracking a lot, and tossing out a lot of code. I feel that you can't work the way I work, unless you are highly experienced (I've been at it over 30 years). I make big decisions, on the fly, and I need to have a really clear idea of the ramifications of these decisions. Often, the devil is in the details. It's quite possible to decide to do something one way, and get there, and then realize that a corner case makes the design unusable, and/or downright dangerous. I'm not a fan of "design by buzzword." Modern techniques are often marvelous, but they can be unsuitable for some applications. Having a toolbox available, that includes a wide range of options, is invaluable. I am a fan of early, high-quality usable product. One of my techniques, is to leverage Apple’s TestFlight beta service, as early as possible. This allows non-tech stakeholders to have meaningful say in the project. Screenshots and interaction diagrams are fairly useless. They take a lot of time (and expense) to create, and no one reads them. They also tend to add unproductive rigidity to the project. [0] https://littlegreenviper.com/miscellany/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/ [1] https://littlegreenviper.com/miscellany/evolutionary-design-specification/ https://littlegreenviper.com/miscellany/evolutionary-design-...

ctvo 5y ago
> I seldom write down a detailed project plan (I write about that here[1]. Feel free to not read it, as well). Instead, my projects start with what I call a "napkin sketch," and evolve, as they progress. The results can be amazing, but I also end up backtracking a lot, and tossing out a lot of code. This is fine for a sketch, a prototype, or an exploration. If you do this to produce production, critical path code, on a professional team with others you're selfish: - The team, not only you, maintains this work that they have no agency over. - You skipped feedback loops, and ignored the expertise of others. - You've removed information sharing and visibility as you go into your cave and come back out with a solution. > I feel that you can't work the way I work, unless you are highly experienced (I've been at it over 30 years). I make big decisions, on the fly, and I need to have a really clear idea of the ramifications of these decisions. Often, the devil is in the details. Yes, the devil is in the details. Get some feedback from other people and stop designing by mistakes I happened to notice and catch. The ones you didn't notice? They're bugs your teammates fix.