"Writing doesn’t just clarify your existing ideas; it generates more of them."
So true! Redrafting and self-editing involves so much more than just getting the commas in the right places. This is how we see new linkages that weren't obvious at first. It's how we become more discerning, so we can define the limits and strengths of our concepts more precisely. And it's one of the best ways of opening up new avenues of thought. (If A is valid, then B, C and D become possible.)
My personal version of rubber duck debugging involves writing an email to explain the problem. It helps solidify my understanding and usually generates new things to follow up on.
For me it happens in cycles. I get inspiration to jazz-up/re-write my blog and that gives me a nudge to write something, anything really, just to get to see something new and that gets the rock rolling and I end up writing half a dozen posts in few weeks. Then I get distracted by some other project or a game or whatever and I forget writing for months and when I remember I have a blog I feel like I don't have anything "worthy" of writing. Until I again get inspiration to start working on the code side of the blog again and the cycle beings a new.
fascinating, writing as a generative process. I like it. Think about how many tangents show up in text that can't be explored fully but can become a subject or book in their own right.
I find reading, writing, and programming can each be incredibly generative in their own ways. I haven't measured its effectiveness, but I like rotating the intellectual crops, as it were. I (at least subjectively) feel most-generative in the few weeks after switching from mostly-one to mostly-another.
When hiring, I always pay close attention to a person's writing skills. I find it to be a useful heuristic for general software engineering competency. But I actually look at this from the opposite direction - someone who's good at writing is usually also good at reading, and being a good reader is extremely helpful in our field. (Good) engineers spend so much time reading: technical books, documentation, requirements, specs, email, and of course code. Engineers who don't mind reading and are able to read attentively tend to be a lot more effective, as they will be more knowledgeable and less likely to miss important details.
Where do I find more people like you when I'm job hunting? :)
I used to work as an attorney before getting into software engineering, and I clearly took for granted that other educated professionals (particular those in a field where precision is required) would write clearly, logically, and succinctly. My expectations have frequently not been met.
It's particularly humorous, as everyone who has hired me has acted like they were taking a big risk because of my non-technical background. Yet, each time, they quickly realize it was a good idea to hire someone with a strong command of the English language and a ruthless attention to detail.
Of course, the technical skills are required as well, but I don't think people appreciate how easy those are to pick up for someone who is capable of reading and distilling voluminous amounts of information in a short period of time.
> Engineers who don't mind reading and are able to read attentively
One very direct application of this skill in day to day engineering is just reading and correctly interpreting error logs and stacktraces.
It's pretty incredible how often that's just the cause of a bug being literally given verbatim, if one can only engage with the message on its terms and frame of reference, and parse out the info from it that's meaningful in the context of the software you're writing (and not, for instance, expecting the error message to somehow do that work for you, which is often impossible).
That's a good point, I think Paul Graham has a similar line of thinking in the relationship between reading and writing. I linked this tweet in my article (https://twitter.com/paulg/status/1618747829975130115) but I've seen other places he's mentioned something similar as well.
I’m a great software engineer but I think by talking not writing. I know others that are visual and draw things from I think and others that code POCs. Maybe that heuristic is more a projection of what you are good at and you look for that in others? Maybe having a team with a written word person, a visual person, an explanatory person, and a code it first person makes a team that can explain what they’ve written with excellent diagramming and a functional POC to demonstrate?
Your brain takes shortcuts, you can think you understand what is going on, it's only when you need to communicate it you realize how many shortcuts in hallucinations of understanding there are in your head.
So for those with imgur accounts... I have a challenge for you.
Most people will know how to ride a bike, will know a bike when they see it.
But can you communicate what a bike looks like (in a diagram)? 90% of you won't be able to.
Grab a piece of paper, and draw a bike. Post it to imgur, and post a link to it below (please don't be a troll).
I know folks that control for this by writing a fail fast implementation. I do it by talking it through. There’s a lot of modalities in the human experience and different people are adapted to different modalities. Building a strong complete team involves covering all the modalities and letting them work the way they work best, and as a team. A team that can write, speak, draw, produce functional demos, etc, is better than the one that can write.
Based on what I saw on that website, only a handful of people couldn't draw a bike well enough to get the point across. A few more than that posted designs which can't function (fixed front wheel), but are easily recognizable as a bike. Most are fine. Certainly not supporting that 90% of people won't be able to do so. A diagram isn't a spec. It's designed to convey higher level ideas of which most of these bike illustrations are fine for.
I’m not sure I understand your point with the bikes. Communication , in writing or speaking, is really just sharing ideas. I saw a lot of drawings of bikes in your link. Are you just saying that people lose the details which ultimately don’t matter? I don’t think of “chainstays” when picturing a bicycle.
they may not even be hallucinations, just short circuit paths that have embedded in your conceptualization of stuff that they've become unspoken deeply furrowed premises long trusted and never thought to be questioned. Surfacing unspoken and unwritten premises is something I find exciting, really invites getting at the root of stuff.
> Writing your thoughts down forces them into a coherent, logical narrative. Condensing your writing gives you a deeper understanding. This process improves your thinking.
When I write something down, it changes my viewpoint. Not sure why, but it does.
I tend to "just do things a certain way," without really planning, structuring, or thinking about it.
I have found that I surprise myself, if I then go back, with a goal of explaining what I do, to others.
I sat down to write a blog series, a deep dive into configuration of our product at a previous job, and I was amazed at how quickly it exposed the parts of our software that I thought I understood but clearly didn't.
As soon as I switched to passive tense, or my brain started to hand wave over something, I knew I'd hit a weak point.
And perhaps unsurprisingly, when I'd check with the engineers, as often as not I'd get the same response: "Huh, I'm not sure either."
I've never found an equivalent tool for identifying my weaknesses. In a conversation I can bluff my way through something and rationalize it to myself or others as "I don't have all the details at hand but I'm sure I understand it"; when writing, I don't have that same luxury.
The first question in writing should probably always be: "Who am I writing this for?"
A lot of the times, in projects, you're writing to yourself, or more precisely to your future self, so that you can figure out in the future what it was you were trying to do in the present. If you've ever come across one of your past projects, and have no idea what it was supposed to do, or where you stopped working on it - that's where a document addressed to yourself would have been invaluable.
If you're writing for some other audience, then it's most important - assuming you want them to read your writing - to try to see the world through their eyes. Technical writing should generally be gradually incremental, starting from minimal assumptions of the audience's knowledge and working upwards. Then, they can read along for awhile at least before having to jump off the train. I recently came across an excellent example of this approach:
As far as non-technical writing, anything goes, be creative, you could be the next James Joyce, which AI is unlikely to ever replicate, or at least probably not.
Reading is somewhat painful for people if it isn't entertaining. When I write things that are information dense at work, I try my best to condense it to be mindful of people's time. It has worked well for me
Definitely agreed - I read my own documentation more than anyone else, and writing it out does make for a better system design, but I never refer to documentation until I _need_ to and I don't expect others to do any differently
X needs to Y stuff bothers me because it’s a “everyone must be like me because I’m like me and that’s the way things are.” I gain none of the things the author attributes to writing. I don’t gain much by drawing pictures either. I do better by thinking a lot then talking it through with someone.
I think a better way to think about it is if you have a team, there’s probably someone on it that gets more done by writing it down and another person who does better by drawing it and another by coding it and another by talking it through. So, talk it through and explain the plan to stakeholders, write it down for everyone to have a definite written explanation of what was talked about, draw the diagrams to explain in pictures what’s complex in words, and code a POC to make it real - and do it together as a team. don’t tell everyone else to be like you, enjoy that they are them and they’re on your team filling the gaps. A sports team isn’t composed of uniform cogs, they take roles that exploit their natural abilities.
Anecdotally, I have found that in doing non-urgent root-cause investigations, writing* is the only way for me to think deeply about a problem.
My flow looks like:
1. Write the impact of the problem as currently observed. This answers most Product and Executive questions and know I'm actively working on solving this problem.
2. List down ideas of what I think it could be.
3. Start exploring those ideas by priority.
4. Bring in Datadog metrics, log items, commands/queries
5. Have a conclusion for each of those ideas
This has multiplicative effects:
1. Others don't feel the need to have me in a Zoom call because they can follow my progress and comment on the doc if they feel strongly about something. I have full focus on the task at hand.
2. The doc becomes handy in outage review meetings and retrospectives later on
3. Useful commands/queries sometimes end up being formed here and I can go back and reuse them
*I rarely actually handwrite things. I depend on Markdown-formatted collaborative notes tools that get out of the way (i.e. not Google Docs).
I think the people who can code well and write good technical documentation are going to transition well into the fully AI-assisted world. So much of what I'm seeing involves not so much the ability to code well, but the ability to write clearly about what you want your code to do. I think the people who can write decent code but struggle to write good documentation (comments and formal docs) are going to struggle to make the transition.
The tools are going to write more and more of the code for us. We're going to be spending more time writing about the code and less time writing code.
(I posted this as a comment on the article, but there's more active conversation here so I pasted it here as well. I'm curious if anyone else has thoughts along these lines.)
During industrialisation the need for physical labour went way down because machines did more work. People on the whole moved less and this contributed to obesity, osteoporosis etc. Loads of gyms, running clubs, etc opened to counteract this trend, to help people stay healthy, but also because voluntary physical activity is enjoyable.
I think we will see a similar transition happening with writing, and perhaps knowledge work in general. The machines do a lot of writing for us, and we will have to do less of it. Writing becomes more of a pastime activity that people do for pleasure, and also to sharpen their thinking and stay sane.
I think we will see an increase in offers for writing retreats, journal clubs, calligraphy classes, etc.
I think we'll see long form writing for the average person go extinct. 200+ years ago, there was much, much less written by the average person, they had no need for it. I suspect we'll return to a similar state.
I think I'm decent at writing overall, I did well in English at school, write up documentation which I am able to point other people to, and find I am able to write quick, clear and actionable responses to emails, chats, etc. When it's a topic I have expertise in, and the audience are pretty much my peers, and it's just a matter of accurately describing or summarizing objective facts about the state of the world, some code, some incident, etc, it's not a problem.
On the other hand, I really struggle with writing up objectives, performance reviews, intern projects, my own resume, product roadmaps, etc. I tend to put this stuff off to the last minute, and spend way too much time making minor tweaks and edits, but probably not improving the overall impact. I'm never sure how much detail is useful vs just going for vague but impressive sounding bullet points.
I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. that more or less live in their own different world, or at least at a different level of abstraction from me. It also doesn't help that it's sporadic stuff that happens once or a few times / year, so I feel I never get good at it or have any kind of feedback loop, and it feels like a distraction from my "actual" coding/day-to-day job, but obviously this stuff actually really important in the long run.
I am really tempted to try to hire some kind of communications consultant to basically sit down with me and do this together, or for me, on an hourly basis or something... much like I do for my taxes. Although maybe I should just learn to do it myself, read a few books / youtube on it, etc... in practice, I don't, and if I found someone who was great at it and it got done, maybe I'd have a better job, better projects, etc.
Really curious to hear of thoughts on this, whether anyone has ever done something like this, whether it worked out... or if the work to find the right person and explain things exceeded the benefits.
It's hard to know if this kind of activity, for me, is a "cost center" that is best outsourced, or a "profit center" that it's a mistake to outsource.
Engineers who proactively communicate in any way at all are worth their weight in gold. Writing consistently will certainly improve quality of communication.
Our org has tools that can look at lines-of-code, number of pull requests, etc.
One of the candidate 20% projects that tempts me is something to keep track of number of words I write in jira. Or slacking with coworkers.
I have great code stats at current job, top tier, but I don't think people have the evidence to really see what I really do. I write. I make our plans. I review the shit out of our work. I help coworkers all the time. (And I write reams of code.)
Great article! Couldn't agree more! I too have realized that when communicating in the async era, more clarity in writing leads to less wasted time. I re-read my messages when sending them to someone to ensure they are clear.
A personal story about how writing helped me make a decision.
A few months back, I was job hunting due to tech layoffs and ended up with two offers from different startups. One was a 2-year-old YC company with a larger team, while the other was a brand-new startup where I'd be the first engineer, building the tech stack from the ground up.
Deciding between the two was tough, so I tried a creative exercise. I wrote draft emails to both hiring managers, explaining why I chose not to join their startup. After about 90 minutes, my preferences became clear.
The only reasons I had for joining the more established startup were job security and better work-life balance. Meanwhile, my passion for the new startup was evident in the email I wrote. This exercise helped me uncover my true feelings.
---
It was a very useful exercise; might be able to help someone else faced with this issue.
What an odd things to say about software engineering... where your job is literally writing. Like telling a newspaper reporter that to get better at their job they should write more. I mean who would have thought that practicing your craft would improve it.
I know the author here is talking about non-code writing but it still sounds weird to hear it given that is our job. To write. I call myself a writer when people ask what I do as it represents it much better than any of the dumb technical names people have come up with. No I don't build houses nor do I design physical artifacts. I write.
Do you guys write for yourselves, or write to present ideas to others?
I mostly write for myself— that's where ideas get figured out. Most of this happens in an Apple Note or in Notion.
I'm apprehensive about all the time I'd be spending polishing something up to put on a blog somewhere, mostly because of the time it takes to explain stuff. We all know that if you take shortcuts and don't speak to a predefined audience, at some point it'll get picked up on HN and torn to shreds...
Often both. After I write something, it feels like it's a free benefit to also share it with others. I'm grateful the Hacker News community is so giving with feedback (eventhough I've gotten torn to shreds a few times haha)
If you want a very short but excellent kick starter for helping yourself become a better writer, I would highly suggest ‘On Writing’ by Stephen King.
It was the first things I ever read of his because I don’t like scary stuff. I was so impressed that I have started to read some of his works… and they are amazing. He is such an amazing story teller.
Highly recommend picking up ‘On Writing’ and letting it guide you towards a future of improved writing skills via practice and helpful concepts.
[+] [-] GCA10|3 years ago|reply
So true! Redrafting and self-editing involves so much more than just getting the commas in the right places. This is how we see new linkages that weren't obvious at first. It's how we become more discerning, so we can define the limits and strengths of our concepts more precisely. And it's one of the best ways of opening up new avenues of thought. (If A is valid, then B, C and D become possible.)
[+] [-] nanidin|3 years ago|reply
[+] [-] lifeisstillgood|3 years ago|reply
[+] [-] nextlevelwizard|3 years ago|reply
[+] [-] jxramos|3 years ago|reply
[+] [-] abathur|3 years ago|reply
[+] [-] playingalong|3 years ago|reply
[+] [-] rmsaksida|3 years ago|reply
[+] [-] bavila|3 years ago|reply
I used to work as an attorney before getting into software engineering, and I clearly took for granted that other educated professionals (particular those in a field where precision is required) would write clearly, logically, and succinctly. My expectations have frequently not been met.
It's particularly humorous, as everyone who has hired me has acted like they were taking a big risk because of my non-technical background. Yet, each time, they quickly realize it was a good idea to hire someone with a strong command of the English language and a ruthless attention to detail.
Of course, the technical skills are required as well, but I don't think people appreciate how easy those are to pick up for someone who is capable of reading and distilling voluminous amounts of information in a short period of time.
[+] [-] davnicwil|3 years ago|reply
One very direct application of this skill in day to day engineering is just reading and correctly interpreting error logs and stacktraces.
It's pretty incredible how often that's just the cause of a bug being literally given verbatim, if one can only engage with the message on its terms and frame of reference, and parse out the info from it that's meaningful in the context of the software you're writing (and not, for instance, expecting the error message to somehow do that work for you, which is often impossible).
[+] [-] ryanlpeterman|3 years ago|reply
[+] [-] fnordpiglet|3 years ago|reply
[+] [-] analog31|3 years ago|reply
[+] [-] 908B64B197|3 years ago|reply
One of the best signal for that is... a college degree.
[+] [-] sinenomine|3 years ago|reply
So, like an IQ test without naming it an IQ test?
[+] [-] mtippett|3 years ago|reply
Your brain takes shortcuts, you can think you understand what is going on, it's only when you need to communicate it you realize how many shortcuts in hallucinations of understanding there are in your head.
So for those with imgur accounts... I have a challenge for you.
Most people will know how to ride a bike, will know a bike when they see it.
But can you communicate what a bike looks like (in a diagram)? 90% of you won't be able to.
Grab a piece of paper, and draw a bike. Post it to imgur, and post a link to it below (please don't be a troll).
Then take a look at https://www.gianlucagimini.it/portfolio-item/velocipedia/
Until you try to communicate a concept or idea in words or diagrams, the chances are you are hallucinating your understanding.
[+] [-] xeonmc|3 years ago|reply
[+] [-] fnordpiglet|3 years ago|reply
[+] [-] tstrimple|3 years ago|reply
[+] [-] leroy-is-here|3 years ago|reply
[+] [-] jxramos|3 years ago|reply
[+] [-] ChrisMarshallNY|3 years ago|reply
When I write something down, it changes my viewpoint. Not sure why, but it does.
I tend to "just do things a certain way," without really planning, structuring, or thinking about it.
I have found that I surprise myself, if I then go back, with a goal of explaining what I do, to others.
Here are some examples of what I mean:
[0] https://littlegreenviper.com/miscellany/thats-not-what-ships...
[1] https://littlegreenviper.com/various/the-road-most-traveled-...
[2] https://littlegreenviper.com/various/evolutionary-design-spe...
etc.
[3] https://littlegreenviper.com/miscellany
[+] [-] macintux|3 years ago|reply
As soon as I switched to passive tense, or my brain started to hand wave over something, I knew I'd hit a weak point.
And perhaps unsurprisingly, when I'd check with the engineers, as often as not I'd get the same response: "Huh, I'm not sure either."
I've never found an equivalent tool for identifying my weaknesses. In a conversation I can bluff my way through something and rationalize it to myself or others as "I don't have all the details at hand but I'm sure I understand it"; when writing, I don't have that same luxury.
[+] [-] ryanlpeterman|3 years ago|reply
[+] [-] photochemsyn|3 years ago|reply
A lot of the times, in projects, you're writing to yourself, or more precisely to your future self, so that you can figure out in the future what it was you were trying to do in the present. If you've ever come across one of your past projects, and have no idea what it was supposed to do, or where you stopped working on it - that's where a document addressed to yourself would have been invaluable.
If you're writing for some other audience, then it's most important - assuming you want them to read your writing - to try to see the world through their eyes. Technical writing should generally be gradually incremental, starting from minimal assumptions of the audience's knowledge and working upwards. Then, they can read along for awhile at least before having to jump off the train. I recently came across an excellent example of this approach:
https://www.scottaaronson.com/papers/pnp.pdf
As far as non-technical writing, anything goes, be creative, you could be the next James Joyce, which AI is unlikely to ever replicate, or at least probably not.
[+] [-] ryanlpeterman|3 years ago|reply
[+] [-] MathMonkeyMan|3 years ago|reply
As for communication, it depends. One problem with writing is that it generates something to read, and people don't want to read.
[+] [-] ryanlpeterman|3 years ago|reply
[+] [-] e_i_pi_2|3 years ago|reply
[+] [-] fnordpiglet|3 years ago|reply
I think a better way to think about it is if you have a team, there’s probably someone on it that gets more done by writing it down and another person who does better by drawing it and another by coding it and another by talking it through. So, talk it through and explain the plan to stakeholders, write it down for everyone to have a definite written explanation of what was talked about, draw the diagrams to explain in pictures what’s complex in words, and code a POC to make it real - and do it together as a team. don’t tell everyone else to be like you, enjoy that they are them and they’re on your team filling the gaps. A sports team isn’t composed of uniform cogs, they take roles that exploit their natural abilities.
[+] [-] cjdoc29|3 years ago|reply
My flow looks like:
1. Write the impact of the problem as currently observed. This answers most Product and Executive questions and know I'm actively working on solving this problem.
2. List down ideas of what I think it could be.
3. Start exploring those ideas by priority.
4. Bring in Datadog metrics, log items, commands/queries
5. Have a conclusion for each of those ideas
This has multiplicative effects:
1. Others don't feel the need to have me in a Zoom call because they can follow my progress and comment on the doc if they feel strongly about something. I have full focus on the task at hand.
2. The doc becomes handy in outage review meetings and retrospectives later on
3. Useful commands/queries sometimes end up being formed here and I can go back and reuse them
*I rarely actually handwrite things. I depend on Markdown-formatted collaborative notes tools that get out of the way (i.e. not Google Docs).
[+] [-] japhyr|3 years ago|reply
The tools are going to write more and more of the code for us. We're going to be spending more time writing about the code and less time writing code.
(I posted this as a comment on the article, but there's more active conversation here so I pasted it here as well. I'm curious if anyone else has thoughts along these lines.)
[+] [-] sieste|3 years ago|reply
I think we will see a similar transition happening with writing, and perhaps knowledge work in general. The machines do a lot of writing for us, and we will have to do less of it. Writing becomes more of a pastime activity that people do for pleasure, and also to sharpen their thinking and stay sane.
I think we will see an increase in offers for writing retreats, journal clubs, calligraphy classes, etc.
[+] [-] linuxftw|3 years ago|reply
[+] [-] tacostakohashi|3 years ago|reply
On the other hand, I really struggle with writing up objectives, performance reviews, intern projects, my own resume, product roadmaps, etc. I tend to put this stuff off to the last minute, and spend way too much time making minor tweaks and edits, but probably not improving the overall impact. I'm never sure how much detail is useful vs just going for vague but impressive sounding bullet points.
I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. that more or less live in their own different world, or at least at a different level of abstraction from me. It also doesn't help that it's sporadic stuff that happens once or a few times / year, so I feel I never get good at it or have any kind of feedback loop, and it feels like a distraction from my "actual" coding/day-to-day job, but obviously this stuff actually really important in the long run.
I am really tempted to try to hire some kind of communications consultant to basically sit down with me and do this together, or for me, on an hourly basis or something... much like I do for my taxes. Although maybe I should just learn to do it myself, read a few books / youtube on it, etc... in practice, I don't, and if I found someone who was great at it and it got done, maybe I'd have a better job, better projects, etc.
Really curious to hear of thoughts on this, whether anyone has ever done something like this, whether it worked out... or if the work to find the right person and explain things exceeded the benefits.
It's hard to know if this kind of activity, for me, is a "cost center" that is best outsourced, or a "profit center" that it's a mistake to outsource.
[+] [-] rukuu001|3 years ago|reply
[+] [-] rektide|3 years ago|reply
One of the candidate 20% projects that tempts me is something to keep track of number of words I write in jira. Or slacking with coworkers.
I have great code stats at current job, top tier, but I don't think people have the evidence to really see what I really do. I write. I make our plans. I review the shit out of our work. I help coworkers all the time. (And I write reams of code.)
[+] [-] reidjs|3 years ago|reply
[+] [-] jatinarora26|3 years ago|reply
[+] [-] asadjb|3 years ago|reply
A few months back, I was job hunting due to tech layoffs and ended up with two offers from different startups. One was a 2-year-old YC company with a larger team, while the other was a brand-new startup where I'd be the first engineer, building the tech stack from the ground up.
Deciding between the two was tough, so I tried a creative exercise. I wrote draft emails to both hiring managers, explaining why I chose not to join their startup. After about 90 minutes, my preferences became clear.
The only reasons I had for joining the more established startup were job security and better work-life balance. Meanwhile, my passion for the new startup was evident in the email I wrote. This exercise helped me uncover my true feelings.
---
It was a very useful exercise; might be able to help someone else faced with this issue.
[+] [-] throwaway138380|3 years ago|reply
[+] [-] eikenberry|3 years ago|reply
I know the author here is talking about non-code writing but it still sounds weird to hear it given that is our job. To write. I call myself a writer when people ask what I do as it represents it much better than any of the dumb technical names people have come up with. No I don't build houses nor do I design physical artifacts. I write.
[+] [-] yawnxyz|3 years ago|reply
I mostly write for myself— that's where ideas get figured out. Most of this happens in an Apple Note or in Notion.
I'm apprehensive about all the time I'd be spending polishing something up to put on a blog somewhere, mostly because of the time it takes to explain stuff. We all know that if you take shortcuts and don't speak to a predefined audience, at some point it'll get picked up on HN and torn to shreds...
[+] [-] ryanlpeterman|3 years ago|reply
[+] [-] MobileVet|3 years ago|reply
It was the first things I ever read of his because I don’t like scary stuff. I was so impressed that I have started to read some of his works… and they are amazing. He is such an amazing story teller.
Highly recommend picking up ‘On Writing’ and letting it guide you towards a future of improved writing skills via practice and helpful concepts.
[+] [-] ryanlpeterman|3 years ago|reply
Here's the Amazon link if anyone else is thinking about reading it - https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft...