Engineers should focus on writing

https://www.yieldcode.blog/post/why-engineers-should-write/

by skwee357 • 3 years ago

238 176 3 years ago

daxfohl• 3 years ago

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.

skwee35711• 3 years ago

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.

tilne• 3 years ago

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

tekla4• 3 years ago

Writing is reasonably easy

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.

tnel77• 3 years ago

I had a professor who graded extremely harshly based on the actual grammar and structure of your lab reports. “A large majority of engineering is writing and you all need to figure that out ASAP.”

I’ve had a relatively short career, but he seems to be correct so far.

gochi• 3 years ago

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.

diatone2• 3 years ago

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?

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.

gloryjulio• 3 years ago

All u need is uml sequence diagram

rco8786• 3 years ago

Writing is reasonably easy and it's hard to get much better than you already are.

Dang you and I have complete opposite worldviews on this.

pxue• 3 years ago

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.

dv35z• 3 years ago

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.

deathanatos2• 3 years ago

Writing is reasonably easy

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.

wsostt• 3 years ago

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.

skwee35711• 3 years ago

I agree with you. I consider writing as one of the MOST important skills in life.

However, being an engineer, and writing in my engineering blog, I targeted mainly engineers.

But yeah, everyone will benefit from good writing skills.

jaylittle2• 3 years ago

It's a shame that more here don't realize that. Being able to communicate is paramount.

arvinsim2• 3 years ago

As someone struggling to write, doing an engineering blog seems to be a fantastic way to start improving.

MisterBastahrd• 3 years ago

If you want to get ahead, writing will not get you very far. I'm not saying that the skill isn't important, but it's down toward the middle of the list in terms of importance. Most managers are average to terrible writers. And yet at the same time, they invariably tend to be better than average verbal communicators, because being able to connect on a social level is vastly more important than being able to connect through prose. You don't have to trust me on this, just look at how political elections are won. Candidates don't submit long articles to the press that support their positions, they get up on a stage and attempt to connect with crowds on an emotional level. It's no different in business. Senior management wants to have managers who can verbally motivate their employees with a short chat and a pat on the back instead of some essay.

crabkin• 3 years ago

I'd be pretty surprised if good verbal communicators aren't usually good writers. I think politicians persuade people not by the clarity, conciseness, or coherence of their speech, but by the substance of their speech. If communication itself could be abstracted from the substance of what is communicated, then it wouldn't be true I think to attribute the success of certain politicians to their ability to communicate so much as their ability to choose what to communicate.

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.

diatone2• 3 years ago

This is an interesting position to take. I’ve been back and forth with my N+1 about the utility of sync vs async comms to lead, and I can never nail down a result I’m happy with. Like, sync comms is effective for ladder climbing as you say. But it has failure modes in remote-first teams of ICs across time zones that async comms don’t have. Async comms inherently scale further, too. Maybe their reach is is greater but the impact is lower? I wonder how far recorded video gets. Then you have mentoring juniors - much easier to do synchronously. What’s the appropriate mix?

MattPalmer10862• 3 years ago

That may be true if you see getting ahead as meaning becoming an ever more senior manager. I do agree that social and verbal skills (and political) skills are important there.

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.

tekla4• 3 years ago

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"

skwee35711• 3 years ago

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.

tekla4• 3 years ago

They don’t explain to you why you need to write, and what are the benefits of writing.

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.

teeray• 3 years ago

They don’t explain to you why you need to write

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.

thfuran2• 3 years ago

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.

tekla4• 3 years ago

You didn't do a capstone project? My capstone was half engineering, half technical report writing. The engineering section was considered worthless unless you wrote a acceptable report. Nobody cares about what you built unless you can write a proper report about it.

How is that possible?

robertoandred• 3 years ago

Anyone who went to college should have taken multiple classes that require you to write. Myopic "engineering schools" miss the point of higher learning.

etimberg• 3 years ago

This is part of the reason why "engineer" is a protected title in many places.

kaycebasques• 3 years ago

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.

EECS at Cal for example doesn't seem to require any TW classes: https://eecs.berkeley.edu/academics/undergraduate/cs-ba

blcArmadillo• 3 years ago

University of Michigan, 2012, a technical writing course was required (TCHNCLCM 300) and it's still required: https://docs.google.com/document/d/1Vh83l2mW6j9P91eqV4W3UbqU...

Uehreka• 3 years ago

Loyola University Maryland, 2012, I don’t know if a technical writing course even existed.

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.

bluepod4• 3 years ago

sewing thread emoji

(Yes, but it was combined with an operating system class.)

xupybd2• 3 years ago

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.

ghaff• 3 years ago

I've never taken a technical writing class but I did work on school newspapers and also took English classes that involved writing.

maxverse2• 3 years ago

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.

[1] www.tinylogger.com

[2] https://twitter.com/maxverse/status/1666095452520058884

[3] https://twitter.com/maxverse/status/1665729476574019585

TheFreim• 3 years ago

Is there an example somewhere showing how it works without signing in?

maxverse2• 3 years ago

Yes, thank you for asking! I've now added screenshots with feature descriptions to the landing page.

electrondood• 3 years ago

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.

nathants• 3 years ago

code.

CaliforniaKarl• 3 years ago

not enough

ronnier• 3 years ago

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.

3cats-in-a-coat4• 3 years ago

Within the next 24 months that's what all engineers will transition to. Is it healthy or not, it's how it goes. Engineers move to abstract work like architecture, interfaces, and the implementation is handled by AIs, with humans just tweaking when it's not right.

bqmjjx0kac• 3 years ago

I'll take that bet.

PartiallyTyped2• 3 years ago

I will take the other side of this bet.

I don’t see this happening within the next 24 months.

xupybd2• 3 years ago

What are you basing this on?

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?

coldtea• 3 years ago

Don't drink too much of the AI kool-aid.

analog31• 3 years ago

Do the AI's need those things? I mean, they exist so that humans can understand their 10 million line code bases. Maybe something else will be needed, for AI's to understand their 10 billion line code bases. Something that we won't even be able to discern.

formulathree• 3 years ago

First: the AI isn't that accurate yet. It gets shit wrong. It's almost there but not yet. Maybe in 24 months... but a lot of people think we hit a wall.

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.

calderwoodra• 3 years ago

As long as they're also reviewing code, I think this is fine. They're scaling their knowledge and impact. Obviously there has to be a healthy ratio of senior:non-senior for this to work as well (maybe 1:4-5?).

zerodensity• 3 years ago

That sounds like good old Waterfall to me. Or in its current form SAFE. 90% communication 10% code. And something like that is basically what it takes when you have hundreds or thousands of people working on the same product.

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.

wiz21c• 3 years ago

yup, 100% true. If you have not worked in such a big company (say more than 500 people), you can't imagine how much politics/communication/organisation/standards/procedures are important both in term of, well, importance, and time you spend on it. In the company I worked, you had about 1 analyst for 2 devs and 1 PM for 10 persons. So more than one third of the team was never writing code. Add in the time spent in meetings, talks, testing, understanding and yeah, I'm sure about 50% of the time was spent not coding.

ravenstine• 3 years ago

Wow, I've never seen anything like this at the places I've worked. In my experiemce, we could use a role like that.

hnick• 3 years ago

Sounds like a Business Analyst and perhaps Technical Writer. Not something the developer should usually spend most of their time doing, but a bit is good.

deathanatos2• 3 years ago

Eh, careful what you wish for. There's two extremes, and I've had the displeasure of seeing them both.

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!

jvans• 3 years ago

If you aren't writing the code you don't understand the problem and can't possibly write the documentation

jbmsf• 3 years ago

Thank you for not having the obvious and boring take. (I also agree.)

LeonB• 3 years ago

Someone reading the code should also be capable of understanding the problem that it solves and documenting the use of the code. If your code is fairly well written, I mean.

von_lohengramm2• 3 years ago

I think you misread the GP. These "mid and senior devs" are writing documents not documentation. They're not writing comments or wiki pages, they're writing designs docs for new systems, proposals for cross-cutting initiatives, etc. They're taking their knowledge of the domain, its issues, and general wisdom and applying it at a scale larger than a single developer's output.

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.

leeoniya• 3 years ago

i'm starting to see this as well.

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.

starcraft2wol• 3 years ago

no longer accurately reflects what are and arent reasonable deliverables

Have you ever seen an accurate prediction of this by any methodology?

octodog• 3 years ago

I literally had a "senior cloud architect" tell me that he didn't understand how one of his team's apps works because "he only draws the boxes" and then laughed it off.

gonzo41• 3 years ago

Don't worry, he knows what you're thinking. It's probably a paralysing deep sadness for him.

valvar• 3 years ago

This is why self-deprecating humour can be dangerous. Some people won't get it and will just think you're an idiot.

magic_hamster• 3 years ago

As my career progresses I find myself reviewing code, mentoring, deciding on architecture and running around helping way more people. I still do hands on coding but my workday had completely changed since when I first started out.

dumpster_fire• 3 years ago

To be fair, unless you're building some low level infrastructural systems, coding is the easiest part, and code is cheap.

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.

spacebanana7• 3 years ago

This depends on the organisation.

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.

doalldrugs• 3 years ago

This would be normal for any other engineering discipline.

floydian10• 3 years ago

I have seen this more and more as well. In my experience, it tends to be developers who are aiming to switch to project management at some point in their careers.

rqtwteye• 3 years ago

Reminds me a little of a lot of interns who all want to "lead". Doing the work is lower class. There is more money in talking about work.

watwut2• 3 years ago

Yeah, but also these interterns are the ones who gets rewarded. The people who do the work do not get visibility and gets rewarded less.

jbreckmckye2• 3 years ago

It's a consequence of scale. Beyond a critical mass of complexity, it becomes more work to envision the moving parts and orchestrate changes among them, than writing the code itself.

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.

ozim2• 3 years ago

Seems like you put too much value on writing code.

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.

blitzar2• 3 years ago

Your company is one consultant away from deciding that your role, as you dont write much code, could be better done by someone who is a full time manager who has an MBA fresh out of university and no coding skills.

TeMPOraL2• 3 years ago

As a senior dev preventing business from bad decisions and preventing code that should never be written is more valuable.

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.

renegade-otter• 3 years ago

It's the culture of over-communication. In the last 8 year or so, I have noticed my ability to actually write code had dropped through the floor. Everything has to be discussed to death, reviewed, approved, and go through a release process and red tape that would make the US State Department blush. And the end result is still slow and inefficient. There is just no time to make it better as you move on to discuss something else to death, while drowning in a sea of Slack messages.

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.

Cthulhu_2• 3 years ago

I dunno, it depends entirely on the industry etc; code is, after all, but the final product, the implementation detail of your company. So many (too many?) developers focus too much on code, on output in lines of code, instead of building the right thing.

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.

jumploops• 3 years ago

From the dawn of times, people were writing.

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-...

antigonemerlin• 3 years ago

Chomsky notes that language was evolved not for communication, but for thinking.

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.

skwee35711• 3 years ago

Very interesting! Thanks for sharing!

staunton• 3 years ago

We're talking about writing. Writing evolved in order to keep track of how much field workers are owed. Make of that what you will.

makeitdouble• 3 years ago

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.

hahn-kev• 3 years ago

I do find that really interesting actually, though I disagree in the context of Code, reading is not a habit, it's a skill you need to practice.

arvinsim2• 3 years ago

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).

skwee35711• 3 years ago

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.

tracerbuilt2• 3 years ago

While I agree with this article in the main, I cannot believe how poorly written it is.

skwee35711• 3 years ago

Author here. Would you be able to provide constructive criticism of what you didn’t like, so I could improve on it next time?

tracerbuilt2• 3 years ago

Sure! The biggest issue is the number of comma splices, which make many of your sentences feel jumbled and disjointed. Aside from that are many more innocent mistakes: “at least” shouldn’t be hyphenated, “ancient” in “ancient Egypt” shouldn’t be capitalized, “one last advice” should be something like “one last piece of advice,” etc. And it could use a good proofing for stuff like “prefect” instead of “perfect” or “make to sense” instead of “make no sense.”

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.

zerbinxx2• 3 years ago

There are some minor grammatical, stylistic, and phrasing issues:

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!

brailsafe• 3 years ago

You're not alone, I thought it was ironic

mrweasel• 3 years ago

That's because writing is hard... Like really hard.

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.

wudangmonk• 3 years ago

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.

soulbadguy• 3 years ago

Don't want to sound overly negative, but the while article is just rehearsing a bunch of platitude about writing...

Also "all great engineer are great writer of code ?"... no not really coding and good engineering are different skills

hospitalJail2• 3 years ago

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.

spondylosaurus• 3 years ago

Instead english spent soooo much time on fiction.

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.

hospitalJail2• 3 years ago

Btw Plato disagrees and I'm with him. (But I am aware of the argument that fiction can intrigue)

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.

sublinear• 3 years ago

I think this is a vital part of any English education

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.

jackson14422• 3 years ago

I think fiction has a place in education for sure, but I think nonfiction, especially longer nonfiction reads (not textbooks, something less dry), should have an equal or slightly larger presence than fiction.

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.

magicalhippo• 3 years ago

When in reality these are all intertwined.

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.

hervature• 3 years ago

Logic necessarily uses words.

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.

high_5• 3 years ago

As long as there are humans involved, yes, there are words, even for visual symbols.

bootsmann• 3 years ago

Actually this is only half true. Formal logic relies on words because some concepts, like finiteness, are impossible to grasp within the formalism itself. A good textbook on this is “Gödel's Theorems and Zermelo's Axioms A Firm Foundation of Mathematics”, which spends the early chapters dedicated to making you aware of this issue.

creer• 3 years ago

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.

langsoul-com• 3 years ago

The don't copy paste statement is eh. Reads like do everything by hand.

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.

eimrine• 3 years ago

My farourite example is vim. Typical scenario of using it is when you do not know what key to press for doing some simple thing but then you put your hands on the keyboard and they do all the work without even involving the brain.

pknerd• 3 years ago

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!

lifeisstillgood2• 3 years ago

What if you wrote code as a form of communication - demos, proof of concepts, snippets.

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

skwee35711• 3 years ago

The thing with writing code, is that often time, engineers are moving away from working with other engineers.

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.

lifeisstillgood2• 3 years ago

My implication is that they should read code. Software literacy needs to be society wide.

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).

throwaway20372• 3 years ago

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!"

cranium• 3 years ago

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.

blitzar2• 3 years ago

"Everyone should focus on being an influencer"

gnz11• 3 years ago

seem to do nothing more than make you anxious about…

Sums up every self-improvement, health and wellness article too. Heck pretty much all of social media.

kaechle3• 3 years ago

Sums up 94.7% of the internet.

Fixed.

lysecret• 3 years ago

Hahaha I love this community. Every time I read a title like this I am looking for a comment like this ;)

kaechle3• 3 years ago

Trite and rehashed groupthink—marketing garbage at its finest. But you should still write. As should every other human being, vocational identity notwithstanding.

skwee35711• 3 years ago

Hey, author here.

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.

schwartzworld• 3 years ago

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.

throwaway20372• 3 years ago

    If the author had emphasized the practical benefits to the average non-influencer-wannabe dev, this article would have been a lot more useful.

This! Or how about some humility: Tell a story about where your communication style didn't work, and what you learned and how you changed. Or tell a story about the worst talk that you ever gave. I like listening to those stories from comedians -- their bigest failure -- and what they learned. With 100% certainty, I have learned more from my failures, than my successes. And too many of my successes were luck. To quote Mike Bloomberg (again on HN!), "Work hard, and you might get lucky."

azangru• 3 years ago

Each time you write a design review

What is this? I've never had to write one.

kypro• 3 years ago

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.

von_lohengramm2• 3 years ago

I'd argue that this is a form of rubberducking.

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.

Noumenon722• 3 years ago

I do this by writing stuff into my notes, but yes! Oftentimes this even improves the solution you were trying to explain. Sure `poetry lock --no-update` fixed it, but why was it updating in the first place...? and I go back to discover an open issue in PyTorch 2.0.1, so I can solve the problem for good by skipping that release.

kaechle3• 3 years ago

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.

mold_aid• 3 years ago

"From the dawn of time, people were writing" In conclusion, there are positives and negatives to writing better as an engineer

castrou• 3 years ago

"All engineers are good writers… of code". Wow wrong in the first sentence. Glad I didn't waste my time reading this article.

DeathArrow• 3 years ago

I rarely learned anything meaningful from "X should do Y" types of posts.

skwee35711• 3 years ago

Hey! Author here.

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.

fnord77• 3 years ago

Is there any empirical evidence for these claims?

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

Cthulhu_2• 3 years ago

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.

skwee35711• 3 years ago

Interesting point! I would take it further and say that it’s not about reading, but about being able to find the needed information.

I won’t read the entire git book, if I only want to create a new branch. I should be able to find it.

taoufix• 3 years ago

The only thing engineers should focus on is, well,engineering.

Engineers should focus on writing

Related Stories