"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.
I have two kinds of people I mentally target when I write documentation: a 6 year old child with an abnormally long attention span, and a grumpy, rude 60 year-old mechanical engineer who isn't quite old enough at the time to skate to retirement before having to learn the thing I'm documenting.
Writing for a child forces me to keep the words and concepts very, very simple, and to write in a style that builds up usage of the program from first principles. Writing for the grumpy old-timer is a practice in minimizing questions from them, forcing me to do a sort of final pass on the overall design of what I'm writing about, to defend design choices, and to add future improvements to the backlog. Drafting the documentation for semi-finished features that are still in progress has sometimes led me to change the design in order to make writing the docs targeting these two people simpler.
lol. that's me; only I start by writing out the problem as an email to ask someone for help. 90% of the time, I find that I didn't have a complete understanding of the problem to begin with, and I usually end up solving it before hitting "send".
Then I'll have this odd memory of - "I discussed this with you, I told you all abo- oh wait, I didn't send it."
I thought I was the weird one...
Many a times have I debugged an issue and was convinced of where is the bug and what the fix is. Only to discover that I was off in both the regards when I sat down to write a detailed email to the team!
I felt I was wasting too much time. But I've realized that for me the time spent writing something in details has always helped me fill in the gaps and also discover the unknowns.
I found that sometimes sending it is required for me when I‘m absolutely stuck and have explained it a few times. It sort of commits it to memory and frees up mental resources then able to come from a different direction.
This is an incredibly common experience, lots of people I've asked do this.
When writing a StackExchange post asking for help, I want to include all relevant information and include a list of things I've tried, along with explanations for why they're dead ends.
Writing it all down sometimes helps me realise that one of the ends is in fact not dead.
This happens more often than I'd like to admit. More often it's on work chat or a call, but the principle holds: I try to explain my problem to someone else and while deepening the explanation, I get a face-palm moment (the answer was there all along!), thank the person for its time and franticly start working on the solution.
Rubber ducking can be a highly productive measure when your mentally clouded and can take many forms.
I've just started using obsidian, but only for a subset of my work, to work on individual documents with a very rigid structure. Do you have any tips on taking obsidian to the next level, using it as an integrated tool rather than just a one-off editor?
The quote refers to the writing process, that by writing you learn of weeknesses in your ideas. It doesnt mean to describe writing as a tool of the week-minded.
(This is coming from someone with ADHD but not dyslexia)
It's harsh, but it isn't wrong, right? The reason that these states of being are considered 'disorders' is because they interfere with daily life and with tasks that other people consider to be easy.
I need to take a lot of time to edit my writing and to re-evaluate the content that I write because it is easy for me to slip into a multi-paragraph tangent. Fundamentally that happens because my thinking is not sharp/focused.
On the other hand, when I am done writing I get a feeling of great accomplishment. Like I was able to swim through the deep waters of my mind and harpoon all the good ideas. Being smart isn't worth much if you can't communicate your ideas!
speaking as someone with mild dyslexia and high ADHD. I would say that my analytical skills, abilty to focus, spatial awareness (I could go on here but I think you get the gist) are well above average based on my work/ university experience
i do take offense of people implying my "mind is weak" based soley on my writing skills. Yes, I know writing skills are important at communicating, but humans have seriously many skills to offer than just writing or even communicating for that matter. yet people seem to be condensing their opinion of other people into a very highlevel simplistic rule. Are we going back in time here? whats next? basing if peoples minds are weak on DNA/ race?
>I need to take a lot of time to edit my writing and to re-evaluate the content that I write because it is easy for me to slip into a multi-paragraph tangent. Fundamentally that happens because my thinking is not sharp/focused.
same here on the first part, but not because I can't focus, its because I have to juggle many train of thoughts whilst writing slowing into one stream of communication. to the point I give up on many things that i really want to say
You are seriously underestimating the importance and potential of communication. Excellent communication conveys expectations, specificity, and manipulation in ways you are not capable of imagining without so being skilled. It’s the difference between effective leadership and being a tool.
If you want to talk about personality the member of the big 5 most correlated with intelligence is openness. The member with the highest negative correlation to intelligence is conscientiousness. To be skilled in any kind leadership you need both high intelligence and super high conscientiousness. To be skilled in writing you need high openness and at least moderately high conscientiousness.
Irrespective of creativity and intelligence you need some amount of conscientiousness to be goal oriented. That is just yourself. To direct others to do the same you need that plus excellent communication skills. There are no shortcuts or alternatives here.
"Writing is nature's way of letting you know how sloppy your thinking is."
As a father to three kids on rhe ASD spectrum, yes I guess you are right. And yeah they need extra time in exams - but honestly no-one writes the final draft the first time. All exams are is how quickly can you regurgitate an essay you wrote (yourself) earlier.
Write, rewrite and repeat. It's the only way. No matter how it bounces around in your brain at some point you mail the slippery thought down and can examine it.
I have an extremely bad short term memory. If you tell me something and I don’t write it down or think about it intensely for a while, I’ll forget it in minutes.
I write everything down because of this. Bullet points, paragraphs etc.
I second it. My brain is also tuned to discard most of the information which is easily available for retrieval through print or online resource. I have to write any new information or concept multiple times In order to retain it for few days.
I have ADHD and maybe some sort of low grade dyslexia. My voracious curiosity with no regard to structured learning or topical coherence has only been a huge boon to my reading/writing. I think ADHD/dyslexia has been a bigger problem in my math and science classes where I write something different than what my brain is thinking, or I make arithmetic mistakes. For instance, if I forget to write the first noun in a sentence, it isn't as huge a problem as when I mix up a summation and summand in an answer or on the way to one.
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.
"Writing about something, even something you know well, usually shows you that you didn't know it as well as you thought. Putting your ideas into words changes them." [0]
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.
I have a journalism degree, and spent a short stint as a reporter before transitioning to engineering.
I share much the same experience: both encountering a distinct lack of effective communication based on what I had expected, and being written off (pun intended) during the hiring process.
My biggest daily struggle is with those who want to verbally discuss every single issue, or worse, chat over informal DMs. Typically those conversations are somehow both circular and meandering all at once.
For me personally, I feel my commitment to writing-competency-over-technical-prowess has been my biggest asset throughout this second act. I'd like to think it allows me to back in to the technical aspects and keeps me better organized overall.
I also have diagnosed ADHD and a form of dyslexia so perhaps I'm just too easily distracted.
p.s. Please don't judge my grammar or spelling on this reply -- I'm writing from the bath with a fever!
>> My biggest daily struggle is with those who want to verbally discuss every single issue, or worse, chat over informal DMs.
That's interesting - I tend to have mixed feeling about this. Sometimes I wish I had all communication done in writting.
But the reality is that as a dev and seminconsultant I work in 10 different domains at the same time and there is no way for me to have enough time to encode all my clients knowledge in structured writing - the only way for my situation to be bearable is to encode this into code and working applications. And the only way to quickly gather knowledge and and have feedback loop on it is to encode it as working applications. Because lets face it even if I was master communicator and writer most clients areny and never will be. And most areny paing for writing text but for providing solutions.
So I'm in this dissonance here where I would love to be better writer but the reality is that its not really that useful in my situation. Ok, and now I feel depressed, thank goodness I just this moment went into confectionery.
Some of the best people I worked with did something else professionally before becoming a software developer. For example army, accountants and electronic engineers. They are the good all rounders, good at going from ambiguity to decent code.
Which is why domain knowledge is so important for software engineers. In most projects. Not always the way the industry works to stay in a given business domain though.
My theory is that the field has a big population "on the spectrum", and they're just not great communicators. Maybe because the "theory of mind" deficit.
They do have extra gifts in writing code which compensates somewhat. But it's a huge problem when half your team struggles to carry a conversation.
I'm not sure there's a correlation between austistic people and (lack of) ability to write "clearly, logically, and succinctly." I think there's a variation of skill there among all people. Some autistic people are excellent technical communicators and documentation or specification/standards writers.
Not exactly a theory that this field has a higher percentage of autistic people. I think the communication deficit is more of a deficit between non autistic people and autistic people.
> 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).
It's surprising how many developers won't even bother to read an error message.
At my list gig there were a few folks who would regularly message me anytime there was a failure in their CI pipeline. No reading the message. Possibly not even opening the failed job at all.
Most of the time, the pipeline was doing what it was supposed to: failing a bad build. It didn't even occur to them that it was their code that was the problem. Just "the pipeline is red: send to @recfab".
> expecting the error message to somehow do that work for you, which is often impossible
But that is in part also because many error messages are closer to "there was an error" than providing full context info. These few minutes more invested into proper error messages can save many many man hours down the line.
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?
One of the points from the article was that writing helps you scale yourself. If you were a great engineer on my team I would want you to write everything down regardless if that was the way you thought through the alternatives or if it was just recording the understanding after you’d gotten to it.
That said, I don’t buy the idea that you reach the same clarity of thought by talking through an idea as compared to writing that same idea down with the intention of communicating it clearly to another person. The latter requires significantly more command over an idea.
Why? Because you can’t? You’re illustrating my point. You are asserting something about my experience without having had it, based on your own. On my teams everyone writes stuff down to their ability, for instance a lot of non native speakers just can’t do a good job of this. But I always have the writer, and everyone works with them to be sure everything of importance is written down in a high quality way. But I judge people by their contribution, not the mode of the contribution. I’ll betcha my teams are more functional, but I’m sure you will disagree so I suspect we have to agree to disagree (but I’ll still poach your nonwriters and non English speakers with aplomb!)
I have to agree with tile and the OP. Even if you have a dedicated formal writer for writing formal documents like briefs or proposals, every engineer should be decent at writing. Especially now that more and more communication is asynchronous.
I've worked with many engineers who couldn't write, and it always came across in the aspects of the work mentioned in the thread — less ability to parse error messages, to describe things to others over email/Slack/comments, and most critically, to understand things that others wrote. Fundamentally, a huge amount of engineering is reading and writing. And I find those skills are very often linked.
Sorry I think I wasn’t clear. I didn’t mean there was a dedicated writer any more than there’s a dedicated speaker or dedicated coder. The conversation is about the mode by which people gain their clarity. A person who gains clarity by writing will naturally gravitate to doing that and will be the dominant writer in the team. But that doesn’t obviate anyone from writing. There are people that gravitate to drawing things out to think things through. That’s where the gravitate, and they’ll likely end up doing a lot of the diagramming. Etc. But everyone participates in every aspect to their ability. The key is recognizing everyone isn’t the same, and that’s not a flaw but a feature. Many managers have a prescriptive view of an engineer and evaluate them like quality control in a widget factory. An excellent manager evaluates the people for their strengths and aligns their work to those strengths. In the foot ball analogy the core skill is running. Everyone runs. But some are really really fast runners. So you have them run really really fast. You let the person who’s really good at throwing be the quarter back. They still run, but it’s not expected they run as well as the fastest runners nor is it a problem. Because the fastest runners are the catchers. If you think engineers don’t come in the variety and shapes and skills as a football team, I don’t think you really understand how teams or humans or engineers work yet and I hope you consider looking at them as individuals and not a prescriptive skill set.
I feel you are putting yourself, and others in a box. We all can gain more clarity from an idea by talking, writing or drawing about it. You don't have to be good at it, it will still improve your grasp of the problem. Of the three, writing is the slowest, meaning your mind takes more time and effort. And the time spent on something has a direct relation to its quality.
Long story short, you will become an even greater engineer by drawing and writing out your ideas.
Sure, of course everyone has different strengths. That might apply to things like one's ability to work with other teams, or being detail-oriented versus being able to see the big picture.
I don't think that applies here. Writing and reading are very basic skills that will help you in all aspects of your job as an engineer, and everyone should be as good as they can be at them.
If we’re going to get pedantic about who can assert what about which experiences: you are asserting that you’re able to reach greater clarity of thought when talking as opposed to writing, correct? But how do you know that’s true? You’re unable to try talking first and writing first for any given task. So although I may be asserting something about your experience without having had it myself, so are you.
On a (somewhat) less pedantic note I would add that “asserting” is a bit strong of a word to describe the statement I made. Perhaps you should be a bit more precise with your words. Writing more could help :).
Nothing wrong with IQ tests at all, in fact we perform them all the time, maybe we call them coding tests, take home projects, or whiteboard interviews from time to time, but they are still a very effective measure of ability.
Each of these has a way to eliminate people I have no reason to hire, including timid/shy people with no backbone of their own, people who are terrible at communicating, people who are clearly out of their depth even in a low stakes environment on a toy problem that doesn't even need to be fully solved.
Communicating clearly doesn't require a high IQ at all, it's a general skill. If anything, high intelligence might be a detriment since a lot of the smarter people I've known can't or refuse to communicate clearly.
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.
Instead of "X needs to Y", how about "consider how Y might help X". The title is a more succinct, admittedly exaggerated, version of what the take-home message should be. It still has a point.
Yes, I agree, it does - if it works for you. if it doesn’t, it doesn’t have a point. But if you read comments on the post you’ll see a lot of folks saying “when I hire I always look at their ability to write” …. This tells me they are writers, writing works for them, this article speaks to them, and they assume it speaks to everyone and anyone it doesn’t can’t possibly be as productive. They assume because it makes them more productive and other modalities don’t that’s the way the world works. This is an incredibly common fallacy, not made of ill will, but it causes all sorts of pain to those who don’t match the hiring managers modality. I know I’m off topic a bit but I think it’s apropos - A good manager looks at the modalities not covered by the team and hires to fill the gaps, but most managers hire to match the modalities they’re familiar with in their own career.
> assume it speaks to everyone and anyone it doesn’t can’t possibly be as productive
Chill mate, it's just some person sharing their own experience and beliefs, they are not assuming anything. I don't know why you feel so opposed and attacked to an otherwise benign topic. The workplace interaction is dominantly biased towards speaking and face-to-face interaction. Even job interviews selects for the extroverts who can talk smoothly and has an outward pleasing personality. A dissenting opinion that argues for the unpopular or minority point of view seems perfectly healthy and natural.
In fact, I find your comment strange. Given the current dominant mode of communication, I would have expected that you would support the idea of writing more. Why? Because you clearly advocate for a balanced team that covers all modality (whatever that means), yet I don't see you pointing out the fact that people dominantly prefers and selects for verbal communication, subtly discriminating people who are more effective in writing or other alternative modes of communication. Instead, you get defensive and even argues against the minority view, clearly contradicting what you seem to be advocating for. What do you say about that?
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).
Google Docs is still doable for these kind of collaborative notes.
I've learned not to worry about anything that isn't content during the process. It can be copied, pasted, formatted, fixed, proof read, and put somewhere more permanent later, just not while I am hard at it.
For collaboration, Google Docs works great. I can't imagine going back to a world where mostly everyone took their own notes (or not) in meetings. Or a world when editing and commenting on a document meant mailing copies around and someone often had to merge diffs manually. Going back 10 years would be a horrible step backward for any sort of collaboration in documents.
(and before someone says it, GitHub/GitLab really isn't a good substitute because they're designed around a different use case. I actually use GitLab for one type of task I'm involved with. Given the final form will be an adoc, it's OK but not really ideal for writing.)
For personal notes that aren't handwritten, mostly anything that will produce a txt file.
It's better these days with code block support and now accepts Markdown shortcuts. But I haven't given it a chance since before those things were supported :)
I do a similar thing. Especially helpful for long-running investigations that are difficult to root cause. Documenting the current state of the investigation allows people to jump in easily and helps everyone tell what the current conclusions are.
I'll bite - what notes tools do you like to use/recommend? I previously used Evernote for everything, but switched to Notion a while ago; neither are great at "get[ting] out of the way" though I think Evernote was probably better in that regard when I used it last...
My company uses Dropbox Paper which does a few things well: Markdown + embedded images (with captions), and collaborative features. I use Notion for my personal stuff, which sufficiently gets out of my way, but never tried it with other collaborators!
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.)
I don't see a future where we replace code with natural language -- and I'm not only skeptical about it, I know for a fact it will never happen: it's an idea that has been tried and did not work. Formal language is easier, for the same reason that nobody in their right mind would rather write "one less than the square of the variable" than "x^2 - 1".
I do agree that writing badly is a reliably correlated with being a bad developer. Not writing well denotes lack of clarity, inattention to detail and self-indulgence, all damning attributes for a serious professional.
A guy at a bar spotted me programming last night and forced a conversation on me about an email-processing script ChatGPT helped him write, and showed me the conversation on his phone.
It struck me, as a programmer with a creative writing background, that he was basically writing microfiction with a character (himself) that needed help, and a character (ChatGPT) to help him out.
as someone that has accidentaly destroyed two laptops with liquid spillages, i have never understood the programming in a coffee shop thing, but doing it in a bar???
I am quite the clutz, and do spill a lot, but I have yet to ruin any device in the process. A few close calls, but none fatal.
I try to mitigate theft/loss/disaster anxiety by keeping a backup/recovery hygiene that enables me to be productive in <2 hours of obtaining a replacement (but I'll sheepishly admit a tool update has the backup script failing atm and I haven't found time to debug).
IME I'm more likely to spill beer on one at home than out and about. Something subtle about space or psychology? (Spaces at home are more likely to be cluttered enough to nudge me towards a risky drink placement? Not habituated to expecting spillables near the computer at home? Idk.)
I did have some jackass having a whiny argument with someone else spill my beer on my laptop this past summer. Close call, but luckily it was almost empty. This was, to some degree, my mistake for going against my gut and humoring his curiosity about what I was doing long enough for him to decide he was welcome to sit across from me.
5. it took about 15 minutes to do something that would have taken him "3 months"
I believe the first 3 but am skeptical of the last 2. He was, in any case, effusive about its capabilities.
For context, I should note:
- he was obviously inebriated, high, and the sort of person who trusted a stranger (me) with his unlocked phone while he went to the bathroom. (I think this actually has a little to say about how quickly he's picking up good prompting?)
- This was at a dive bar in Houston's east end--not really a tech hub.
Edit: he was persuasive enough that I intend to try to shift more of my habitual queries from Google to chat gpt until I at least have a deeper grok of effective prompting than I have picked up so far.
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.
> I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc.
You seem like a smart person. If you don't understand who is reading it and why, then of course it'll seem like meaningless busy work, and you'll have trouble writing it well.
I'd consider telling your manager how you feel, and ask them for help writing these well. Kind of a pair programming session. I bet you'd get a ton out of it.
I kind of do - I often just ask for feedback on things (more detail? less? happy with the prose or want bullet points?), or work on things together on a screen share where possible, etc.
Sometimes people help and provide feedback which is great... but sometimes they don't, because I guess my boss is busy with his own stuff / reports / etc, or if I am writing my own objectives / appraisal for him, then he is in fact the person that needs to be persuaded, or has his own competing interests, etc.
I think it's less about getting feedback on the work product (how is this good or bad? what should I change?), which is emotionally taxing for the feedback giver. What you want is the context of how it's going to be used (what meeting will this be presented in? what leaders will have access to it? what are the problems these people will be trying to solve?). If you know the answers to those things, and can get a sense of how your boss is working, you'll be able to give yourself the feedback you need on whether your deliverable fits the bill.
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.)
I agree, but I also generally am not super opposed to having data. The potential for misuse is very high. But I know I'd rather have it, even though it could mean anything.
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.
"I re-read my messages when sending them to someone to ensure they are clear."
Kudos for doing that! I hate when people treat writing messages like a second hand skill that doesn't deserve any effort, especially when explaining technical stuff.
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.
I'll bite. I mostly write for me. Because my memory is unperfect, because it shows gaps in my understanding, it forces me to gather all the links, resources, references. Because it feels so much more concrete than other software/computer endeavors.
It's also a great help to closing a topic. Once everything is put down and said, I can checkpoint in trust that I'll be able to restore later. Closing all the open loops. For some time at least.
And sometimes, most of the times, I end up sharing with interested parties. Either because someone needs to write up a conclusion or synthesis, and (very humbly) better me than someone else, especially if I'm the one doing or driving most of the work.
If you share widely, sometimes it's also a way to find other kindred souls, or to have a place to come back 'see, someone tried this and it worked'. And to challenge oneself against a larger public and see whether you need to improve in some ways.
Just don't look too much at HN or Twitter downers (use the mute and block features heavily), try and focus on positive and constructive, additive comments. Push back, shut down, leave alone anything harmful. It may come with the need for additional therapy sessions (it did for me the first times), so please beware.
It doesn't need to be a fight. I hope whenever/if you feel like writing something and share it, that I'll be able to read it and maybe enjoy the thoughtful ideas or conversation or inspiration, the challenge.
I love that feeling that I get writing for closure, when I'm distilling and crystallizing things that I've learned about a topic. I use physical notebooks for that kind of writing, and writing the words out by hand once I've understood something just feels so nice and durable. And then I can page it out of my brain, knowing the notes are there if I need them again.
(By contrast, I'll usually have a temporary digital file with notes in flux while I'm learning something. But the notebooks are where I write things "on-the-record.")
How deep do you want to get? The benefits I think outweigh the downsides, we formed the modern world by advancing ideas.
But I share you sentiment, I don’t write, too many fights to win. There is a significant portion of the workforce who do not do anything except to try an take up the air in a conversation.
I don’t post on HN, often write out the comment, refresh the tab and move on because of what I see that will unfold. Sometimes things need to be said, but often it’s the things that are not said that paint the picture.
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.
Not many do. I will alternatively use the work programmer as I think it also contains something closer to the idea of what we do. But people blank when you tell them that vs. if you tell them you are a writer it might spark at least a bit more conversation.
So what you're saying is, essentially, that you've managed to increase engagement by actively misleading people? I'm not sure what to tell you, but congratulations on inventing clickbait for small talk!
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.
Writing is undervalued by a lot of software engineers. It is the best medium for sharing information, live (thanks to collaborative documents), but also over time (documentation). An essential skill to develop.
I do believe however that fewer and fewer engineers will actually take time to develop that skill and will rely on ChatGPT and co in the future to generate most of the written content based on draft notes.
I highly recommend picking up a book in writing and style. I enjoyed Dreyer's English (Strunk & White, while commonly recommended, is a little antiquated). There are so many avoidable mistakes like subject-verb agreement, attaching adjectives to the wrong noun ("A violent, intense, affair, Stephen King has written another fantastic novel" -> Stephen King is a violent, intense affair), and so on.
The classic English teacher advice is also very much worth following, such as reading aloud and creating an outline.
And of course, reading is a fantastic way to improve your writing. There are examples of great writing in any genre or format, but I would say that fiction and long-form journalism are usually quite good, while non-fiction books and blog posts tend to be more hit or miss. Sometimes you need to read a little James Baldwin to remember that writing can be an art form and not just a perfunctory means towards an end.
My biggest hang-up wrt writing is prose, specifically maintaining & iterating on prose. I would rather write in a graph, but have not found any tools which serve my purposes to replace a physical notepad in this regard.
Tools like The Brain is ok but I would rather have source files which I can commit to a repo. Dendron is ok as well but is not universally inteoperable...as I use Jetbrains tooling. I can't deny how important the somatic & muscle memory elements are to the task of writing & VSCodium is just not on the same level as Jetbrains tools.
What would be great is to have a Universal ID & a graph api where all of my writings can be queried & updated or amended.
For now, software is more satisfying to write than prose. I hope experience of writing in a digital format can become more like writing graph data structures in the near future.
writing prose is a skill like any other - the more you do it, the better you get at it, the faster and easier it goes. I would outright say doing it without tools is a better learning experience than using tools.
I hear you & appreciate that prose is an art & craft in itself.
Prose, iconography, pictures, spoken word, voice inflection, body language, etc were the only games in town before the advent of computers. Now we have algorithms, graph data structures, set logic, as tools to work with information. Prose can be analyzed using NLP, but it is verbose, full of throwaway words, & the expression of scoped intent of meaning can be improved.
One major weakness of prose is the difficulty of gauging breadth & completeness of expression. When writing software, it is easier to perceive if a program is incomplete. Compilers, type systems, automated tests, & runtime errors guard against bugs or issues with syntax or logic.
It is more difficult to parse the prose to understand if all of the essential pieces of information (i.e. logical premises followed to their conclusion) is present in the document. If a conversation is started about a document pointing out missing logic or a fallacy, it is difficult to counter a chain of reason other than quoting phrases & responding to those phrases, possibly taking the phrases out of context. There is also a trend toward rivalrous attention dynamics in online conversations. If you look at Hacker News, many of the threads repeat each other & the disagreements quickly turn into bickering. Such patterns of conversation could even be identified with simple algorithms with can be open.
A graph data structure allows the context to be transmitted so if a phrase in a graph is quoted, the context comes along with it. If the phrase is separated from the contextual graph, the meaning changes. An assertion or counter assertion could be tested using Set logic. Phrases are less likely to be taken out of context, diminishing strawmen. The full breadth of unique points can also be aggregated. I think tooling with expressions being in a graph would also disincentivize bickering & rivalrous attention dynamics.
The cool thing about writing software is that one participates in the trend of evolved tooling of expression. Whether it's writing a library, creating a program or app, writing a language, an experiment of expression is conducted.
I think you'll find that people aren't programs, and that learning to write prose without graph data structures and algorithms will make you a better communicator, and is worth the exercise on its own even without conducting experiments on expression.
The ultimate goal is communication, not experiments.
I write prose & am dissatisfied with maintaining & editing statements made. Prose is one method of communication, but people often talk past each other or respond to a cherry-picked statement without addressing the full context. If the listener sees things from primarily their position, it often doesn't matter how good you are at prose. If there is more explicit structure in the communication then a fuller context could be more visible. Prose is serial & requires repetition, which is duplicate effort.
Given how online discourse has devolved in the recent decade, it seems that the modality of prose is lacking certain elements which brings shared understanding & context.
Prose is also inefficient to read. We train our vision to fixate on certain words & glyphs to derive the meaning of a sentence. If the format were more friendly to scanning to understand context & meaning, we could also more efficiently understand content & find links to other related content.
Thank you. I briefly looked at it a few months ago. I have a difficult time leaving the rest of my tooling. It is great for what it is, but I think what I'm looking for does not has not been implemented yet.
I learned to write properly while doing my Ph. D. Basically, if your main job is publishing articles, that is not optional of course. And since English is the dominant language to publish in, I had to learn English as well (my native language is Dutch).
An eye opening insight I had while I was learning to write properly was that I was doing a lot of things systematically wrong. So, the job became learning to do it right in a systematic way. This didn't happen overnight but I learned from my mistakes one by one and started criticizing my own writings based on that and slowly improved what I was doing. One by one, I was eliminating whole categories of mistakes and learning why they were mistakes.
Another thing that I learned was that putting a lot of effort in writing creates a sunk cost fallacy. You start becoming defensive of all the text you have write. Learning to rewrite your text and stepping over your reluctance to delete stuff you have written is a key skill. Iterating makes things better. It's literally faster to rewrite than to correct text. If it looks or feels wrong, just delete it and write it again.
Another insight is that writing things down forces you to make your fuzzy ideas concrete. You get progressive insight from rewriting things that you've already written. This works better if you wait a bit for your short term memory to purge itself of any notions you might have. You can use time to your advantage here. Simply take a break and rewrite or revise what you have written later. Weekends and sleeping are great for this. You come back fresh and you instantly spot all the mistakes you made earlier.
People think of writing as an art form. Which of course it is. But in many ways, writing is like programming. It is governed by simple rules (grammar and stylistic ones). All you need to do is learn those rules and apply them. There's a certain logic to how a good text flows. How sentences and paragraphs connect, etc. The whole job of learning to write is figuring out how that works.
Tools actually exist that can check your writing automatically these days. Use those and don't argue with them and instead fix the issues that these tools will point out to you and learn about why those are issues that need fixing. Once you stop producing text that has loads of such issues, you'll have become a better writer. It's not that hard. But you do need to make an effort. And of course know to use and install such tools.
And since programmers indeed depend on written communication, this is a good skill to have.
People tend to also underestimate the value of humor and pacing in writing. Injecting a little bit of comedy into everything you write (including technical specs) can be incredibly valuable.
God yes. Good humor is so hard to do when writing about technical things. I try to get a good balance by judicious application of surrealism, but a lot of the time your jokes won't land, and your references are both too old and too young for your coworkers simultaneously.
I try regardless, but it's very hard to avoid accidentally irking coworkers.
If I have too many ideas floating around my head I will forget some of them. So I write them all down as short bullet points, and skim them when I'm stuck.
This article did a good job making me want to write more.
But it didn't do anything to explain how to write as an engineer. Like the author I didn't enjoy writing in school, so how does writing as an Engineer differ, and how does one improve ones Engineering writing.
I remember that someone mentioned vomit writing and vomit coding a while back in hn. I think it's the same principle. Just write^TM has already made me more productive and more focused
> I hated writing in high school. It wasn’t objective like my favorite subjects, math and science. It also didn’t help that we had to write about old, hard-to-understand literature like Shakespeare.
While I never considered myself an engineer, but a computer scientist, I've always loved writing.
My favorite course in high school beside programming was literature and language.
I never stopped writing in a form or another. I love Shakespeare as much as I love any other old or new good author.
Considering Shakespeare old and hard to understand doesn't tell us as much about Shakespeare as about you.
The inflation the sales went down so much lately that my local supermarket stopped selling m&m’s, snickers, mars, kit kat, …. They only sell the store brand now.
Was genuinely searching for the the stuff and asked a clerk, they said that stuff's gone so pricey people don't buy any more... It's honestly a little worrying
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.)