Ugh. Another one of these blog posts. Engineer is a good communicator. Has a blog. Gives talks. Then starts navel gazing: "Hey, other engineers should focus more on what I'm good at." I'll get downvoted for this last one: The blog has a link at top of page <<Get a FREE coaching session with me.>> Cringe. This whole thing reads like an advert for his services.
Financial advisers are exactly the same with their "weekly newsletters" that seem to do nothing more than make you anxious about your financial portfolio and think: "Hey, I need some coaching!"
The author of the article is right when he says that writing code is often the easy part of the job for many people. The people who hand out promotions don't read your code, but they do read your writing and hear you speak.
I write documentation, do presentations and demos, do code reviews, and even primarily communicate with colleagues through text. The truth is that people who are better writers have an easier time doing this sort of thing. If the author had emphasized the practical benefits to the average non-influencer-wannabe dev, this article would have been a lot more useful.
I think public speaking classes (or at least practice) and even speech/accent coaching would be beneficial for many developers for the same reasons. Your ideas are only as good as your ability to get people to listen to you, and if you go up the ranks as a developer or transition to management, this only becomes more important.
I get your point. The internet is filled with pseudo-gurus that try to sell you stuff by writing shit-posts.
I’ve been writing for over 10 years. Many posts were scrapped and thrown away. I’m an autodidact, so I learned from blogs like mine. I try to write quality content only, it’s not always possible, but I try.
The coaching session you mentioned, is indeed free. The newsletter, is free. And you are not obligated to sign to any of them, you can just enjoy the content if it helps you. I tried to design the blog to be as clean as possible, and that posts will be its center.
I also believe that people should be compensated for their efforts. It feels like software engineering is the only industry where people don’t want pay. If I write - I should do it for free, without cringy banners. If I make a software - I should give it away for free with source code attached. If I mentor - I should do it for free. But that’s not how the world works. It’s perfectly ok to give away content for free, which will help to promote other services. And if this makes you anxious, then you should avoid that type of content.
Good points, but it does not invalidate the content. I particularly like the structure of this blog post: each title is direct and the paragraph below gives its substance. Structure is paramount for technical writing.
Trite and rehashed groupthink—marketing garbage at its finest. But you should still write. As should every other human being, vocational identity notwithstanding.
Something that I’ve noticed at my company and other companies friends work at is an increasing number of software engineers who do not write code at all. They just write documents, comment on documents, go to meetings, and ask questions in emails. Lots of these types where I work and where my friends work (very well known companies). I do not think this is healthy for a company to have its mid and senior devs writing no code in the numbers I’m seeing.
I would add that good writing is required for all career advancement.
Senior engineers or architects may do more design than coding and the design needs to be conveyed likely as writing and hopefully a couple diagrams.
Managers absolutely need to be good writers to communicate effectively, advocate for their team, and tell the story of the team’s work.
If you’re an engineer and want to have a higher level job than you have now, getting better at writing is only going to help. I’m not saying it’s a MUST because I’m sure there’s some outliers, but it won’t hurt.
One of my gripes about k12 is how english was seen as the opposite of Math/Science.
When in reality these are all intertwined. Logic necessarily uses words. Science might make some equations, but the scientific method is going to use words.
Instead english spent soooo much time on fiction. It really hurt my interest since I was often a contrarian when it came to fiction and my teachers hated it. I thought I was bad at English, turns out teachers didn't like me.
The first time I figured out I was good at English was when my wife, a 4.0 student read a college English paper for me and she was shocked she said "YOU ARE GOOD AT EVERYTHING".
I don't think I was actually that good, I struggle so much writing professional/scientific papers, my readers apparently agree because I'm quite limited in my reach. Meanwhile I see others write juicy content.
Maybe I have a problem with clickbait/marketing/copywriting.
Pictures are worth a thousand words. Writing is reasonably easy and it's hard to get much better than you already are. If I had it to do over again, I'd spend a lot of time learning drawing and diagramming tools. They still intimidate me, and I'm always blown away by people who can whip up a diagram showing exactly what they are thinking.
Incorrect. My professors trashed students reports (that groups had spent literally 800+ man hours on) because they were all awfully written. Writing well is incredibly hard, especially on technical topics.
Diagrams for many engineering topics is worthless since diagrams are unable to actually express complex topics very well.
Pictures are worth a thousand words but if you don't know which words you want to communicate your picture is worthless. Something many artists eventually learn, what is it you actually want to say?
Diagramming is interesting because it relies heavily on writing, half of a diagram are words. You can slap on as many triangles, circles, and lines as you want to communicate your idea but if you do not utilize the right words it's a worthless diagram.
An HTTP request-response diagram is a great example of this. You can overcomplicate it with both symbols and text, you can also miss crucial points and give people the wrong idea entirely.
So let it encourage you to pick up drawing/diagramming tools, and improve your writing even further. Take already made diagrams, how would you improve them? If someone asked for clarity on how to expand on that diagram (ie: how would an ISP fit into the HTTP diagram), what would that look like and what symbols and text would you use?
Another fun challenge to improve on writing is how would you explain (topic) to someone who is blind? It's more difficult than you think as we tend to rely so heavily on visual information, but it's a fantastic way to improve your skills by highlighting weak points in cross-type information.
> Writing is reasonably easy and it's hard to get much better than you already are.
I can't fathom how you've arrived at this conclusion. Like everything in life, the only way you can know for certain if something is true or not is by doing it many times over and then seek feedback.
Until one writes and then shows their writing to many many readers, it is impossible to make such claim.
> writing is reasonably easy and it’s hard to get much better than you already are
This is the complete opposite of my personal experience. (I do agree with your point about the value of diagramming. But I see it more as a subset of the foundation of writing: clearly expressing thoughts in an easily readable medium
All I can figure is that their laptop didn't come with the red squiggle underlining feature, much akin to how some cars on the road very clearly didn't come with a turn signal.
I agree with you! The art of making great images and diagrams, is required as well. But I consider it the next step, after improving your writing skills.
Check out Affinity Designer. There’s a MacOS version and an iPad one - if you have an iPad & pen, definitely get it.
It’s a vector graphics tool - and it’s in a good sweet spot. Easy to make simple and useful diagrams - export them as transparent PNGs and start incorporating them into documents, presentations.
Any engineer that went to college should have taken multiple technical writing classes. Engineering school vigorously demands that you learn how to write properly and accurately, something that seems lost on "web engineers"
The problem with school, or college, is that they tell you, you need to write. They don’t explain to you why you need to write, and what are the benefits of writing.
That’s why most design reviews are very painful to read, and understand. That’s why company wiki becomes a pile of useless information.
It really doesn't. I got an engineering degree without taking a single technical writing course. Not counting short physics lab write-ups, I think I wrote a single technical paper during undergrad.
I've never heard of CS undergrad programs requiring a technical writing (TW) course, let alone many. Can we do a quick poll? Leave a comment with the name of the university where you got your CS undergrad degree, the year (or decade) you graduated, and whether or not TW courses were required.
Anyone who went to college should have taken multiple classes that require you to write. Myopic "engineering schools" miss the point of higher learning.
I picked Engineering as it didn't have any writing requirements. Now I wish I'd spent more time writing. It's a skill that I need and want to develop now that I understand how the world works better than I did as a university student.
If you're looking for a distraction-free writing tool, I've been building and using a minimal blogging platform called Tinylogger[1]. My focus is on a totally clean interface (everything goes away while you write [2]), and I recently shipped a no-judgement mode [3] that focuses you only on the line you're writing, fading everything else out - perfect for first drafts and morning pages. I've been blogging a lot more this way.
I was hoping the article would compare how writing code and writing a fantasy, sci-fi, etc. novel are very similar. I find writing stories to be a better analogy to use with programming than civil engineering or architecture.
Its very easy for another engineer/architect to look at some building plans and make an addition to the structure. Now compare that to how easy it is for a different writer to finish the work of another. The second is a lot more difficult to do. This is probably the reason why rewriting is always the default choice when a new group takes over a code-base.
The big difference is that in programming you have instant feedback when something is inconsistent in the story (compilers/interpreters). Writers have that too, they are called fans but they're not as reliable and not every writer gets that luxury.
I feel a disconnect between what the writer probably wants to say (which is kinda meh...everyone's brain is different, good for the author if he found something he enjoys), and the actual argument they're pushing, which is more interesting to be honest.
> All engineers are good writers… of code.
> Writing is a way to organize your brain
> Writing is a way to learn something
> Writing helps you identify mistakes
> Remember–reading is a habit, writing is a skill. And in order to prefect your skill, you need to write more.
Basically, "write more code if you're good at it, you'll learn a lot, organize your brain, and improve your skills" is also a decent takeway from this.
I've read an iteration of this blog post every week for the last decade, but something I've been doing recently and has actually helped (far more than writing) which I've not ever read a blog post about is simply explaining technical concepts out loud to myself.
I'm a very bad communicator due to being autistic and unlike writing as developer I often find myself in position where I need to discuss some technical concept with other developers on the team. Occasionally I also have to communicate technical aspects of my work with those on the team who are non-technical. I really struggle with this.
At the end of each day I'll now do a 10 audible recap of what I've done. Anything I struggle to explain I spend a little time thinking about how I can be clearer and try again until I'm happy. I then take some notes and I have something for standup the next day, but also I'm hoping that consciously focusing on how I explain things is helping a with my ability to explain things on fly.
I'm still in the early stages of learning how to code, but I've started doing something similar to help me get into the right mental state. As someone with severe ADHD, it takes serious effort to get the brain waves waviating at the right frequencies. If I mentally check out, even for a couple of hours, it's like I completely forget everything I've worked on.
Out of frustration, I started talking through my code out loud, and the difference was incredible. All my mental scaffolding and abstractions sprang to life, where before it would've taken an hour or two of rereading my code and rebuilding everything in my mind. Now I'm a chatty bird, typing and mumbling to myself as I work.
Also, not to discount your struggle, but don't write yourself off as a bad communicator—pun intended. I spent 15 years in tech, then seven years writing marketing content, and now I'm transitioning back to tech. Words are hard. The ability to string them together coherently does not make someone a great communicator. Like writing code and engineering, it's easy for laymen to conflate the skill with the vocation.
Keep practicing—you'll eventually outshine those who think opening their mouths and making noises is necessarily good communication. And check out some famous speakers who're on the spectrum if you haven't—you'd be surprised.
While I agree, reading is the other part. I - and so many others here I'm sure - have spent so much time answering questions that were documented. It's just that nobody reads the documentation, or can't find what they need fast enough, or they just have no patience because asking someone feels faster - to them.
I can write long documentations and comments on everything, but it's wasteful if it's not kept up to date and it's waste if nobody bothers to read it.
With others here I deplore that my schools did not teach a number of important life and career skills including writing. They did teach english, did an excellent job of it. But they did not teach writing FAST. By now I feel a key to productivity (or plain day to day viability) is being able to draft, reorganize, prune, edit and ship out FAST. That deserves teaching.
Hilariously, most Google hits in this direction are about handwriting speed. I have to add "productivity" and the like to get anywhere.
Writing is also a very useful tool for guiding/directing the conversation.
Create a document that lays out the approach you want, share it, and then have a meeting about it where people can react to it. If you get everyone together and try to decide something democratically, it's a shit show. Documents allow you to put a stake in the ground, and depending on how much colleagues care, what you write is 95% of what ends up in the product.
It's not about engineers only. Every human who can read and write MUST form a habit of writing. It does not matter you write in Shakespearean language or not, what matters you convert your thoughts into words. If you feel embarrass of sharing your thoughts, just do it privately, in a diary or online private blogs like Wordpress but DO WRITE ANYWAY!
For me, the biggest obstacles to improving in writing is getting feedback. It's hard because you need to ask people to read what you wrote and feedback is very subjective.
It's really different from software development where you can get immediate feedback without outside help(I am aware code reviews exist).
Feedback is subjective in every field you take. I’ve got a lot of “NITs” in my code reviews, which essentially are - subjective feedback.
I do see where you are coming from regarding getting feedback. I’m pretty sure there are places, like Reddit communities, where you can get feedback about writing.
But I also want to point out an interpreting observation, that I can’t explain. I’ve noticed that the more I write, the better I become at it, regardless of whether I get feedback or not. Future articles are becoming easier to write, sometimes clearer. I also see an improvement in my oral communication. So maybe practice, for the sake of practice - does make perfect.
[+] [-] throwaway2037|2 years ago|reply
Financial advisers are exactly the same with their "weekly newsletters" that seem to do nothing more than make you anxious about your financial portfolio and think: "Hey, I need some coaching!"
[+] [-] schwartzworld|2 years ago|reply
I write documentation, do presentations and demos, do code reviews, and even primarily communicate with colleagues through text. The truth is that people who are better writers have an easier time doing this sort of thing. If the author had emphasized the practical benefits to the average non-influencer-wannabe dev, this article would have been a lot more useful.
I think public speaking classes (or at least practice) and even speech/accent coaching would be beneficial for many developers for the same reasons. Your ideas are only as good as your ability to get people to listen to you, and if you go up the ranks as a developer or transition to management, this only becomes more important.
[+] [-] skwee357|2 years ago|reply
I get your point. The internet is filled with pseudo-gurus that try to sell you stuff by writing shit-posts.
I’ve been writing for over 10 years. Many posts were scrapped and thrown away. I’m an autodidact, so I learned from blogs like mine. I try to write quality content only, it’s not always possible, but I try.
The coaching session you mentioned, is indeed free. The newsletter, is free. And you are not obligated to sign to any of them, you can just enjoy the content if it helps you. I tried to design the blog to be as clean as possible, and that posts will be its center.
I also believe that people should be compensated for their efforts. It feels like software engineering is the only industry where people don’t want pay. If I write - I should do it for free, without cringy banners. If I make a software - I should give it away for free with source code attached. If I mentor - I should do it for free. But that’s not how the world works. It’s perfectly ok to give away content for free, which will help to promote other services. And if this makes you anxious, then you should avoid that type of content.
[+] [-] gnz11|2 years ago|reply
Sums up every self-improvement, health and wellness article too. Heck pretty much all of social media.
[+] [-] blitzar|2 years ago|reply
[+] [-] cranium|2 years ago|reply
[+] [-] lysecret|2 years ago|reply
[+] [-] kaechle|2 years ago|reply
[+] [-] ronnier|2 years ago|reply
[+] [-] wsostt|2 years ago|reply
Senior engineers or architects may do more design than coding and the design needs to be conveyed likely as writing and hopefully a couple diagrams.
Managers absolutely need to be good writers to communicate effectively, advocate for their team, and tell the story of the team’s work.
If you’re an engineer and want to have a higher level job than you have now, getting better at writing is only going to help. I’m not saying it’s a MUST because I’m sure there’s some outliers, but it won’t hurt.
[+] [-] hospitalJail|2 years ago|reply
When in reality these are all intertwined. Logic necessarily uses words. Science might make some equations, but the scientific method is going to use words.
Instead english spent soooo much time on fiction. It really hurt my interest since I was often a contrarian when it came to fiction and my teachers hated it. I thought I was bad at English, turns out teachers didn't like me.
The first time I figured out I was good at English was when my wife, a 4.0 student read a college English paper for me and she was shocked she said "YOU ARE GOOD AT EVERYTHING".
I don't think I was actually that good, I struggle so much writing professional/scientific papers, my readers apparently agree because I'm quite limited in my reach. Meanwhile I see others write juicy content.
Maybe I have a problem with clickbait/marketing/copywriting.
[+] [-] daxfohl|2 years ago|reply
[+] [-] tekla|2 years ago|reply
Incorrect. My professors trashed students reports (that groups had spent literally 800+ man hours on) because they were all awfully written. Writing well is incredibly hard, especially on technical topics.
Diagrams for many engineering topics is worthless since diagrams are unable to actually express complex topics very well.
[+] [-] gochi|2 years ago|reply
Diagramming is interesting because it relies heavily on writing, half of a diagram are words. You can slap on as many triangles, circles, and lines as you want to communicate your idea but if you do not utilize the right words it's a worthless diagram.
An HTTP request-response diagram is a great example of this. You can overcomplicate it with both symbols and text, you can also miss crucial points and give people the wrong idea entirely.
So let it encourage you to pick up drawing/diagramming tools, and improve your writing even further. Take already made diagrams, how would you improve them? If someone asked for clarity on how to expand on that diagram (ie: how would an ISP fit into the HTTP diagram), what would that look like and what symbols and text would you use?
Another fun challenge to improve on writing is how would you explain (topic) to someone who is blind? It's more difficult than you think as we tend to rely so heavily on visual information, but it's a fantastic way to improve your skills by highlighting weak points in cross-type information.
[+] [-] pxue|2 years ago|reply
I can't fathom how you've arrived at this conclusion. Like everything in life, the only way you can know for certain if something is true or not is by doing it many times over and then seek feedback.
Until one writes and then shows their writing to many many readers, it is impossible to make such claim.
[+] [-] rco8786|2 years ago|reply
Dang you and I have complete opposite worldviews on this.
[+] [-] tilne|2 years ago|reply
This is the complete opposite of my personal experience. (I do agree with your point about the value of diagramming. But I see it more as a subset of the foundation of writing: clearly expressing thoughts in an easily readable medium
[+] [-] deathanatos|2 years ago|reply
clearly not
give the number
of enginers i see
write like this
all the time
message choke full
of typso
---
All I can figure is that their laptop didn't come with the red squiggle underlining feature, much akin to how some cars on the road very clearly didn't come with a turn signal.
[+] [-] skwee357|2 years ago|reply
[+] [-] dv35z|2 years ago|reply
It’s a vector graphics tool - and it’s in a good sweet spot. Easy to make simple and useful diagrams - export them as transparent PNGs and start incorporating them into documents, presentations.
[+] [-] gloryjulio|2 years ago|reply
[+] [-] antigonemerlin|2 years ago|reply
Murphy (of Murphy's law fame) notes that you're not really thinking if you don't write the thought down: you just think that you're thinking.
[+] [-] jumploops|2 years ago|reply
Nit: before writing was invented, humans were able to pass knowledge over many generations via oral means.[0]
[0] https://www.scientificamerican.com/article/ancient-sea-rise-...
[+] [-] tracerbuilt|2 years ago|reply
[+] [-] soulbadguy|2 years ago|reply
Also "all great engineer are great writer of code ?"... no not really coding and good engineering are different skills
[+] [-] tekla|2 years ago|reply
[+] [-] skwee357|2 years ago|reply
That’s why most design reviews are very painful to read, and understand. That’s why company wiki becomes a pile of useless information.
[+] [-] thfuran|2 years ago|reply
[+] [-] etimberg|2 years ago|reply
[+] [-] kaycebasques|2 years ago|reply
EECS at Cal for example doesn't seem to require any TW classes: https://eecs.berkeley.edu/academics/undergraduate/cs-ba
[+] [-] robertoandred|2 years ago|reply
[+] [-] xupybd|2 years ago|reply
[+] [-] ghaff|2 years ago|reply
[+] [-] maxverse|2 years ago|reply
[1] www.tinylogger.com
[2] https://twitter.com/maxverse/status/1666095452520058884
[3] https://twitter.com/maxverse/status/1665729476574019585
[+] [-] TheFreim|2 years ago|reply
[+] [-] wudangmonk|2 years ago|reply
Its very easy for another engineer/architect to look at some building plans and make an addition to the structure. Now compare that to how easy it is for a different writer to finish the work of another. The second is a lot more difficult to do. This is probably the reason why rewriting is always the default choice when a new group takes over a code-base.
The big difference is that in programming you have instant feedback when something is inconsistent in the story (compilers/interpreters). Writers have that too, they are called fans but they're not as reliable and not every writer gets that luxury.
[+] [-] makeitdouble|2 years ago|reply
> All engineers are good writers… of code.
> Writing is a way to organize your brain
> Writing is a way to learn something
> Writing helps you identify mistakes
> Remember–reading is a habit, writing is a skill. And in order to prefect your skill, you need to write more.
Basically, "write more code if you're good at it, you'll learn a lot, organize your brain, and improve your skills" is also a decent takeway from this.
[+] [-] hahn-kev|2 years ago|reply
[+] [-] kypro|2 years ago|reply
I'm a very bad communicator due to being autistic and unlike writing as developer I often find myself in position where I need to discuss some technical concept with other developers on the team. Occasionally I also have to communicate technical aspects of my work with those on the team who are non-technical. I really struggle with this.
At the end of each day I'll now do a 10 audible recap of what I've done. Anything I struggle to explain I spend a little time thinking about how I can be clearer and try again until I'm happy. I then take some notes and I have something for standup the next day, but also I'm hoping that consciously focusing on how I explain things is helping a with my ability to explain things on fly.
[+] [-] kaechle|2 years ago|reply
Out of frustration, I started talking through my code out loud, and the difference was incredible. All my mental scaffolding and abstractions sprang to life, where before it would've taken an hour or two of rereading my code and rebuilding everything in my mind. Now I'm a chatty bird, typing and mumbling to myself as I work.
Also, not to discount your struggle, but don't write yourself off as a bad communicator—pun intended. I spent 15 years in tech, then seven years writing marketing content, and now I'm transitioning back to tech. Words are hard. The ability to string them together coherently does not make someone a great communicator. Like writing code and engineering, it's easy for laymen to conflate the skill with the vocation.
Keep practicing—you'll eventually outshine those who think opening their mouths and making noises is necessarily good communication. And check out some famous speakers who're on the spectrum if you haven't—you'd be surprised.
[+] [-] Cthulhu_|2 years ago|reply
I can write long documentations and comments on everything, but it's wasteful if it's not kept up to date and it's waste if nobody bothers to read it.
[+] [-] skwee357|2 years ago|reply
I won’t read the entire git book, if I only want to create a new branch. I should be able to find it.
[+] [-] creer|2 years ago|reply
Hilariously, most Google hits in this direction are about handwriting speed. I have to add "productivity" and the like to get anywhere.
[+] [-] electrondood|2 years ago|reply
Create a document that lays out the approach you want, share it, and then have a meeting about it where people can react to it. If you get everyone together and try to decide something democratically, it's a shit show. Documents allow you to put a stake in the ground, and depending on how much colleagues care, what you write is 95% of what ends up in the product.
[+] [-] castrou|2 years ago|reply
[+] [-] pknerd|2 years ago|reply
[+] [-] arvinsim|2 years ago|reply
It's really different from software development where you can get immediate feedback without outside help(I am aware code reviews exist).
[+] [-] skwee357|2 years ago|reply
I do see where you are coming from regarding getting feedback. I’m pretty sure there are places, like Reddit communities, where you can get feedback about writing.
But I also want to point out an interpreting observation, that I can’t explain. I’ve noticed that the more I write, the better I become at it, regardless of whether I get feedback or not. Future articles are becoming easier to write, sometimes clearer. I also see an improvement in my oral communication. So maybe practice, for the sake of practice - does make perfect.