Engineers should focus on writing
yieldcode.blog
yieldcode.blog
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!"
Sums up every self-improvement, health and wellness article too. Heck pretty much all of social media.
Fixed.
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.
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.
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 don’t see this happening within the next 24 months.
The various LLMs do very poorly at generating and implementing high level designs, especially if they need to generate the specs themselves from a bunch a requirements and/or poorly formulated user feedback.
That for sure will scale on larger projects!
I've played with code generation from AIs it works sometimes but confidently produces bugs and doesn't scale at all.
I think another giant leap is required to get to the point that humans are just tweaking. I'm saying we won't get there but what in the pipeline in the next 24 months that is going to get us there?
What I base my guess on: the fact we already have GPT apps that write apps and clearly it works fine, and as we like to say "this is the worst it'll ever be". When people say "it's not very good right now, it produces garbage" I only see people who are not used with the speed of progress right now. Midjourney a year ago produced weird abstract doodles that only looked like images from distance. Now it produces photorealistic art that's taking jobs. One year.
What we need: Bigger context, expert models in constellation and scale. You need nothing else. Of course some architectural modifications will emerge in the journey of achieving this, but that's a comparatively trivial constraint to solve, it's just normal software engineering as we've done for decades, but this time for models.
Second: implementation is harder then design. If AI can do implementation it can for sure do design. And it is demonstrably true that chatGPT can do design just as well if not better than implementation.
Making sure that everyone understands how to use your part (and that the overall architecture is at least coherent), in a big project, is actually more important than if that part is of high quality. And since communication is more important it's the seniors responsibility.
Sometimes I really want to go back to the junior years it was in general more fun back then. But getting to decide the architecture does have its charms.
The first is those who write only code, with no regards for the overall design or documentation of the system, and are completely unable to formulate answers about the high-level functioning of the system, often ask for things based on a low-level need with no regard for what could or should happen at a high level, because nobody has the high level picture.
The other one is armchair architects who will draw system diagrams utterly disconnected from reality, with sub-systems doing things they cannot do, that we will never hire the engineering to do, etc. They'll mandate "common APIs" and "everything must be REST" (but where REST is their personal vision, which is inevitable not RESTful at all, and often is just a bespoke RPC/HTTP style API).
There's a happy medium in the middle: engineers who understand the code, can be productive in the code, but also understand and are making conscious decisions about what the highlevel should be, making design docs, emailing about intentions, etc.
Management has to offer the environment for that to flourish though: there has to be the time for documentation, the time for the design to emerge and for bugs to be worked out. But if everything is just a PM's pet ticket that is due "yesterday" and it must be done because management decrees it and once it is, repeat? Then that'll never happen, and those eng will quickly find greener pastures.
Sometimes it's really petty stuff, too. I've lost the fight of "engineering needs a mailing list to discuss technical changes, TDDs they'd like a review on, etc. There needs to be an alias for engineers to do engineering" — and yeah, no TDDs have happened since!
My current gig is basically the first one. Nobody has the big picture. Nobody wants to discuss the big picture. They are only interested in checking off the boxes associated with the task they currently have assigned. Everything is due yesterday because there is no actual priority list and our priorities shift on a daily basis. It's utter chaos.
We are writing an ERP system. It is slowly shaping up to be a complete disaster. I have spent the last eight months trying to change this approach and attempting to lead by example.
It's not working. I will be moving on soon.
TLDR: Just because somebody can afford to hire a software engineer, doesn't mean they should hire a software engineer.
Most importantly it doesn't tell us what we're not doing here, and why not.
I find myself adding comments to my own code when 6 months after the fact I'm re-discovering why something that looks casual is really important. Why that one "obvious " improvement or optimization is -not- done.
But that's documentation at the lowest level. Most of my documentation time (and I'll admit to writing a lot of docs) is about a bigger picture; hoe is the code used, what problems does it solve, how it interacts with the world and so on.
Documentation is not about writing the obvious "this increments x", its about making the code reusable, making it useful to yourself and your colleagues, my noting that it exists.
It I'd if you like the "search index" into the code.
In theory, this makes perfect sense and is a great way to amplify a more senior developer's impact compared to just coding "the hard stuff." In practice, unfortunately, this leads to a "doc culture" where there's often too much focus on the writing & documents and not enough on the coding & getting shit done.
For example, look at Amazon. Writing is considered a core SDE skill, yet atrocious code (especially from more senior "lifers") and shitty half-solutions are seemingly desirable. Promotion at Amazon is about telling a story of your impact in your promo doc, not about explaining to the powers that be that you're a kick-ass engineer who needs harder problems.
it's frustrating because capacity planning expects that all engineers / ICs write code at least 75% of their time. the effect is that titles+headcount no longer accurately reflects what are and arent reasonable deliverables / deadlines for a team.
Have you ever seen an accurate prediction of this by any methodology?
Drop any senior dev into coding duty, and their skills return after one to two weeks. On the other hand, asking a junior dev to implement a new system that integrates with 3 other departments, and you'll have to wait two quarters for them just to figure out who to talk to and how to get consensus.
If an enterprise has well defined interfaces for teams to interact with one another and effective escalation points for conflicts in priorities then communication might be the cheap & easy part.
Conversely, small modifications to a messy codebase can be extremely time consuming. Imagine being asked to fix an animation bug on an in house date picker in a large Angular app that hadn't been updated in 5 years.
Personally, I think most software systems could accept fewer moving parts if we allowed certain tradeoffs, and the benefit would be much more empowered engineers.
As a senior dev preventing business from bad decisions and preventing code that should never be written is more valuable.
Code is liability.
To propose solutions I still need to know the code for the system so it is not like suddenly I lost ability to write or understand code. But coding - is only one of many tools for creating a system.
In the end, knowledge of the business details (including their technical implementation) are something that cannot be easily replaced.
Except, this could be done better and cheaper by a literal rock with letters spelling "NO" written on it with a sharpie.
If a software company doesn't write any code, what exactly is it doing? And speaking of bad decisions, surely some have been made already, since everyone is doing the job they're the least qualified for.
Not all companies are “software companies” and it still takes level of maturity to know when to write code and when to outsource.
At the interview for my n-2 job, I was interviewing with the director of IT and a junior to mid level dev.
The mid level dev asked me how I would write an address validation module.
My answer was that I wouldn’t and went into details all of the complications of validating addresses and that I would use 3rd party CASS software. I went on to explain that from what I know about the core business it wouldn’t be a competitive advantage and that “it wouldn’t make the beer taste better”.
The software dev wasn’t impressed, the director was.
I was hired as a senior dev and I was ruthless about using third party software from reputable companies instead of writing code internally. This company has no desire to hire a bunch of devs.
We had specialized consultants for Salesforce, Workday, our data capture system, learning management systems, AWS and everything else.
In about a year and a half, I put myself out of a job, they went public and are running smoothly seven years later from what I can tell talking to former coworkers.
But I sure did have a great story to tell interviewing for my current position working in the consulting department at BigTech.
It made no sense for a health care company that sent at home nurses to special needs kids to write their own in house EMS/EHS system. And they had an in house one that they had been depending on in 2015. It was built using PowerBuilder from 1999 and running SQL Server 2000. They were “locked into” supporting an old PowerBuilder app.
It also wouldn’t have made sense to hire a bunch of mobile developers to write a data capture system written for Android devices for their nurses. I had been there done that eight years prior when I did work for a company that wrote field service software for ruggedized Windows CE devices and 5 years prior when I did something similar for rail car repairmen.
It also wouldn’t make sense for them to write anything that could be done with Salesforce or a third party LMS.
Software developers are a cost center to a non software company.
There's not much more I can add, but there's something I must pick on, in the name of countless users who suffer because of this:
> My answer was that I wouldn’t and went into details all of the complications of validating addresses
So far, so good...
> and that I would use 3rd party CASS software.
Why? The correct answer almost universally is: "I would not do that thing, period, because it's a lose-lose idea that hurts both you and your customers". Same with validating people's names.
EDIT: Since downthread you mention it was a system "for a health care company that sent at home nurses to special needs kids", part of which involved said nurses doing data entry... I wonder how much those nurses loved the address validation "feature" and how many serious issues (as in, with actual consequences to someone's health) it caused.
For a lot of industries, bulk address verification is a requirement to get a cheaper mailing rate. I first started using it when I was working for a SaaS company that printed and mailed bills and statements to customers.
It also a requirement for medical billing.
At one level I understand it. Gone are the days of us hacking away as an island, playing around, experimenting. Software engineering is more mature, boring, and corporate.
This is why in a lot of companies, internal tools (like issue trackers, performance monitoring, logging, orchestration, testing, etc) are written and rewritten over and over again. The idea that building your own is better than using off the shelf software. But it's self-gratification, it's avoiding the company's own / real problems and products.
Writing code without a plan or purpose is wasteful.
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.
However, being an engineer, and writing in my engineering blog, I targeted mainly engineers.
But yeah, everyone will benefit from good writing skills.
Most of what you write will be skimmed or not read at all. The only way to increase your odds is to make your writing engaging (to improve chances of it being read) and clear and concise (to improve chances of comprehension).
Another oft overlooked skill is to know when to repeat your message in multiple places, and how to do so without it being irritating or noisy or irrelevant (see also: when not to write anything at all). Again, this increases the chance your message gets across.
Early in my career I took something that was technically complex for me, and wrote it up as a book, using the path that lead me to understanding it.
Assuming that some of my peers might benefit from what I learned, I "self published" (aka printed copies on demand on my newly bought double-sided printer) and sold it for $50. I sold about 1000 copies over the next few years.
The money wasn't earth-shattering, but the effect on my career was immense. I was the one who literally "wrote the book". As far as resumes go, it's pretty up there.
Part of the success (I think) was that it was specifically designed to be an easy read. The goal was to get to the end and "know" a bunch of stuff, without it ever being anything but obvious.
I think it was helped by understanding where my own mental blocks were, and by unpicking those blocks, allowed others to easily disassemble and pass them.
In my experience the biggest block to learning is in understanding that something we absolutely positively know to be true, is actually false. Without letting it go first your brain refuses to accept the new (however simple) because it clashes with what is "true". But that's a digression for another thread.
It's completely alien to me that people here seem to believe engineers should be spending time making requirements and architecture documents more engaging. You're paid to read the thing, just read it.
Your goal is to get your message across when your writing is skimmed.
That takes immense skill as a writer. Immense skill.
Paris Review is a great book to get an overview of mastering this skill.
A writer has to be interesting though, every piece of writing we consider well written has a quality of gripping the mind. I'd argue then, that politicians though they may not be in the habit of writing long academic style treatises or "interesting" articles, perhaps it can be argued in the past they largely did, still if they are in part elected on the basis of their speech, must possess the same ability in writing.
If you don't believe me then how is it that Trump's tweets are works of art, "I have never seen a think person drinking Diet Coke,"The Coca Cola company is not happy with me--that's okay, I'll still keep drinking that garbage.", etc... Crude, in bad taste, whatever you say. Another example is Obama, who honestly has a gift for writing in the conventional sense.
You can also have incredibly skilled orators where it’s all in the substance, but you can really only do that if you message actually has substance to it in the first place.
My own verbal and political skills aren't great. I am not a manager! Writing well has been good for me personally in terms of being able to organise my own thoughts better, and to be succinct in a way I can't when I speak.
I find my opinion is consulted frequently partly because I can summarise complex issues and present it in a way others can work with.
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.
Respectfully, I think this is a vital part of any English education—the more you read, the better your writing becomes. Conversely, it's very difficult to become a proficient writer without becoming a proficient reader first, and for school-aged children, fiction is both the most accessible point of entry (although good nonfiction can capture kids' imaginations, too) and a great way to cultivate analytical skills.
Fiction sets unreasonable expectations. Why not use history? The bad guys sometimes win, but at least people learn something closer to reality.
How much time was wasted learning about symbolism? How much time did we waste learning how to be entertained?
Today I do none of this. Non-fiction is far more interesting than someone making stuff up. I'd much rather have good reading and writing skills than the ability to decode entertainment as an adult.
History, and I say this with a degree in the subject, does not do the same thing. History too is important, but it is not art, it's a social science. It's a complex field, assuming you mean the study of history and not just telling stories from the past, which half of the time is basically fiction. History is a way for us to understand our past and past and contemporary modes of thought, but it does not fulfill the same role as fiction.
I enjoy reading fiction, mostly for escapism although the good ones also enrich me, but there is plenty of non-fiction that can feed those qualities. Non-fiction that focuses on the psychology, motives and feelings of people, and focuses on special, different , or creative individuals, might dk just that.
The autobiography "Lab Girl" comes to mind.
How does this sound appealing?
Fiction does not require bad guys to loose. That is just contemporary American cultural expectation to make them always win.
>How much time was wasted learning about symbolism?
If you want to communicate with people, symbolism matters. It is part of the communication, just like analogies or figures of speach.
I wouldn't say "vital". There are plenty of examples everywhere since language is like air. Fiction may be great art, but that's not representative of what most people write. I agree there should be a better balance. When I was growing up we didn't even analyze famous speeches until high school which is far too late.
My favorite english class was either technical writing or freshman comp 1 because both were focused on nonfiction pieces, which was so rare elsewhere in my education.
I'm not a great writer. I hated Norwegian at school.
But I've helped both my SO, my sister and others improve their college grades significantly by simply doing a pass on their hand-ins. They'd write an essay or similar, and I'd just check that their arguments were consistent and made in the right order.
If I found their arguments lacking I'd ask them, they'd explain what they meant and I said "great, put that in there". Other times it was just a matter of swapping segments around. Simple stuff like that.
I wasn't versed in the things they studied, they knew their stuff but they just struggled to put it in writing. I'm not a good writer, it's not what I do. But as a programmer, getting arguments consistent and in the right order, well, that's basically my day job.
I'm surprised no one has challenged that statement. Logic is making deductive statements that are true. One only needs symbols for this. That's why computers can prove mathematical theorems. Words are necessary because we are human and we need to communicate are base assumptions which normally come from the natural world. Saying logic necessarily uses words is like saying logic necessarily uses eyes or ears.
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
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.
I’ve had a relatively short career, but he seems to be correct so far.
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.
If I had a dollar for every time someone drew a diagram that expressed their thought, but didn’t explain all the hidden assumptions and omissions that clear writing would flush out, I would be a poor man since they wouldn’t need me to review their work.
Dang you and I have complete opposite worldviews on this.
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.
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.
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.
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.
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-...
But again, I really dig where you went with the article. I think you make a lot of good points and that your advice to learn by writing is great stuff. It could just use some polish.
It’s just an excuse though, and I’ll try to be more mindful the next time.
> From the dawn of times, people were writing. We have written using symbols, like in Ancient Egypt. And we have written using letters, like in Renaissance times
"From the dawn of time" is somewhat of a cliché in starting an argument, adding the "s" to "time" makes it a malapropism. This isn't a great way to start a post on the importance of writing. I would generally expect this to be phrased "Since the dawn of time". You, like many writers, have a tendency to over-signify the independence of clauses, leading to a bit of turbulence. Your second and third sentences could be phrased:
"We have written using symbols, like in Ancient Egypt, and we have written using letters, like in Renaissance times"
I'm not going to be a stickler about the "sentences shouldn't start with 'And'". This couplet isn't wrong per se, but the lack of specificity in your writing doesn't exactly scream "I know the history of the written lanuage!" Don't be afraid to be specific. In both the cases of Egypt and the Renaissance there were earlier cases of symbol-based and letter-based writing systems. Researching, naming them, and giving the reader that extra bit of context will make your writing more engaging.
There are also tense conflicts between these two sentences: one is firmly rooted in the past tense while the other lands in the present perfect tense. This is a big ol' nitpick but once you start really paying attention to tense you start to notice that tense-disagreement can make writing sound disjoint. One way this could be rephrased or improved upon is to focus on tense agreement and be more direct in what you're saying:
"Since at least 3400 years ago, people have used writing to communicate ideas. Ancient Egyptians and Mesopotamians had complex language systems that revolved entirely around the use of symbols. As language evolved, words and letters gave writers a near-infinite sandbox of concepts and tools with which to communicate. By the time of the Greeks, alphabetic languages like Aramaic, Hebrew, and Sanskrit were used the world over to preserve and communicate ideas."
A few more examples:
This is a big misconception, we all fall for. -> This is a big misconception that many software engineers fall for. (comma overuse) (unclear "we") (overgeneralization in using "all")
One simple way to write more–is to approach design reviews in a different way. Instead of hating them, and doing them like a homework assignment, try to approach them with enthusiasm -> One simple way to write more is to approach design reviews in a different way. Instead of hating them or treating them like a homework assignment, try to approach them with enthusiasm (hyphen misuse, comma overuse)
One last advice–abolish the copy-paste. So many developers, whom I mentored, simply copy-paste everything. Code snippets, function declarations, etc. I know how to initialize a git repository, because I do it by hand every time -> One last piece of advice: abolish the copy-paste. Many developers I have mentored simply copy-paste everything from code snippets to function declarations. I know how to initialize a git repository because I do it by hand every time. (comma overuse, hyphen misuse, unnecessary sentence snippet).
I would like to echo the other commenter that I really agree with the message here, and think it's illustrative that you're getting feedback on your writing after posting it here. If you never write, nobody will ever have the chance to give you feedback. Keep it up!
It’s broader than just grammar, more like rules for good writing which could almost be automated.
Are there a set of rules or a good book I can refer to?
I also recommend the left-to-right, "topic position -> stress position" approach described in https://www.americanscientist.org/blog/the-long-view/the-sci.... I care more about whether I am making the reader do unnecessary work than whether I am entertaining to read or whether my commas are spliced.
I've been tasked with writing a page or two about a project I'm currently working on and I'm finding it incredibly difficult. It has really highlight to me that I need to write more, if I want to be able to communicate more clearly.
Also "all great engineer are great writer of code ?"... no not really coding and good engineering are different skills
That’s why most design reviews are very painful to read, and understand. That’s why company wiki becomes a pile of useless information.
Then thats a bad school or program. It was drilled into us nonstop that lives depend on writing good reports. You do not want to be the person blamed because your report was vague or misleading. Bad writing kills people.
That is a failure of the professor. I was blessed to have a professor with an engineering degree, a writing degree, and industry experience as a technical writer. He was uniquely qualified to teach engineers how to write and why good writing was important.
How is that possible?
EECS at Cal for example doesn't seem to require any TW classes: https://eecs.berkeley.edu/academics/undergraduate/cs-ba
Edit: But I do want to note that I love and appreciate good technical writing, and have gotten a lot of experience doing it in the workplace. It’s a really important skill, but with undergrad curriculum so jam-packed already, I can see why it might not be a required full-semester course.
(Yes, but it was combined with an operating system class.)
[1] www.tinylogger.com
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.
> 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'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.
Something that I've tried a few times was basically pretending that I'm a live-streamer/YouTuber/whatever and verbally explain my thought process & actions as I program. I found that it was actually better practice for coding interviews than anything else, but I wouldn't be surprised if you found trying something similar also helpful.
I do think there is specific value in practicing summaries, though, as it's a really important skill to be able to distill down a 45-minute technical rant into something grokkable by others in a reasonable amount of time. Something that I do most mornings is plan out my exact phrasings for standup updates, sometimes verbally if I'm having troubles putting my update into words and I'm WFH that day. Then again, I'm probably a bit autistic too and often mentally plan out most non-casual conversations.
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.
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.
I won’t read the entire git book, if I only want to create a new branch. I should be able to find it.
Hilariously, most Google hits in this direction are about handwriting speed. I have to add "productivity" and the like to get anywhere.
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 really different from software development where you can get immediate feedback without outside help(I am aware code reviews exist).
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.
This would work - but only if the people you communicate to are software literate.
Yes english matters but sometimes it's just easier to write code to show the ideas work
The more scope you get at your work, the more you work with non coding people: an architect that might not code in your language, a PM who might not code at all, a team lead who is not a programmer, a potential client.
Look loads of managers these days say "I used to code but now I moved to management I don't do that."
No one says "I used to read and write English but now I have moved to management I don't do that". Because sometime around 1500 using writing to communicate and set policy became so powerful that's how you ran a large (religious) organisation (in Europe).
When I can google the answer in a min. Or if you use AI, even less, why bother?
Our brains can be used for more important details than how do I reset a git branch.
It seems to me writing about learning a new programming language makes you better at writing, not necessarily better at learning the new programming language
What type of posts help you learn meaningful things? I try to improve my writing all the time, and would love to experiment with other formats, that might benefit more people.
What is this? I've never had to write one.