14 ms·
Engineers should focus on writing
- tracerbuilt 3y agoWhile I agree with this article in the main, I cannot believe how poorly written it is.
- skwee357 3y agoAuthor here. Would you be able to provide constructive criticism of what you didn’t like, so I could improve on it next time?
- tracerbuilt 3y agoSure! 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.
- skwee357 3y agoThank you very much, I appreciate it. I usually run my articles through proofreading, but I’m in a process of switching to a different text editor, and didn’t setup proofreading yet. It’s just an excuse though, and I’ll try to be more mindful the next time.
- zerbinxx 3y agoThere 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!
- benjaminwootton 3y agoHow do I learn to analyse and critique my own writing in this way? 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?
- zerbinxx 3y agoEats, Shoots & Leaves is a good one on punctuation. Dreyer’s English is a good recent one. Woe Is I is a classic. There are a lot of style guides and fun little books about grammar and editing. My partner is a editor at a publishing house so she guides me a lot on things like this. I’m not sure it can be automated, but the best things I can say I’ve learned about writing are: don’t do anything obviously wrong (grammatically, syntactically, factually), be concise/specific, and keep your purpose/relationship to the reader at the front of your mind.
- zero_shift 3y agoThere is a great book called _Style: Towards Clarity and Grace_. Any of Joseph Williams' other books will do if you can't get hold of that.
- Noumenon72 3y agoSteven Pinker's _The Sense of Style_ is good at grounding style rules in the actual evolved structures of human grammar. I also recommend the left-to-right, "topic position -> stress position" approach described in https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing 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.
- brailsafe 3y agoYou're not alone, I thought it was ironic
- mrweasel 3y agoThat'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.
- deleted 3y ago[deleted]
- daxfohl 3y agoPictures 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.
- tilne 3y 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
- skwee357 3y agoI 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.
- tekla 3y 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 3y agoI 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.
- gloryjulio 3y agoAll u need is uml sequence diagram
- wsostt 3y agoI 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.
- skwee357 3y agoI 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.
- jaylittle 3y agoIt's a shame that more here don't realize that. Being able to communicate is paramount.
- oscillonoscope 3y agoIn my experience, writing skill rarely matters as much as people think. A large portion of my coworkers won't bother to read what anyone wrote or put effort into comprehending it. I try to make good documentation but I know it's pretty much just for my future self.
- IneffablePigeon 3y agoThis is _exactly_ why it is important. 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.
- tekla 3y agoAny 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"
- skwee357 3y agoThe 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.
- tekla 3y 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 3y 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.
- robertoandred 3y agoAnyone who went to college should have taken multiple classes that require you to write. Myopic "engineering schools" miss the point of higher learning.
- thfuran 3y agoIt 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.
- maxverse 3y agoIf 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 https://twitter.com/maxverse/status/1666095452520058884 [3] https://twitter.com/maxverse/status/1665729476574019585 https://twitter.com/maxverse/status/1665729476574019585
- electrondood 3y agoWriting 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.
- ronnier 3y agoSomething 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-coat 3y agoWithin 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 3y agoI'll take that bet.
- PartiallyTyped 3y agoI will take the other side of this bet. I don’t see this happening within the next 24 months.
- 3cats-in-a-coat 3y agoWe already have apps written by non coders in GPT. But sure let’s wait 24 months.
- WJW 3y agoWe also had apps written by "non coders" in excel. We had apps written by some hackthon participants who hadn't coded at all a week before the hackathon. Writing the code is not the hard part of software development, and never has been. 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.
- nathants 3y agocode.
- CaliforniaKarl 3y agonot enough
- jumploops 3y 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-tale-told-accurately-for-10-000-years/ https://www.scientificamerican.com/article/ancient-sea-rise-...
- antigonemerlin 3y agoChomsky 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.
- makeitdouble 3y agoI 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 3y agoI 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.
- arvinsim 3y agoFor 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).
- skwee357 3y agoFeedback 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.
- wudangmonk 3y agoI 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 3y agoDon'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
- hospitalJail 3y agoOne 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 3y 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.
- hospitalJail 3y agoBtw 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.
- SketchySeaBeast 3y agoFiction gives us things to shoot for, and a way to envision tomorrow. Think about all the things that science fiction envisioned that became reality. Would we have strived for those goals without it? It can also help us understand each other on a level that describing real events can't. Good fiction is art. We need art, and we should be able to be able to interact with it on a sophisticated level. I'm surprised if you honestly find all fiction uninteresting. 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.
- jasmer 3y ago[dead]
- creer 3y agoWith 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 3y agoThe 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 3y agoMy 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 3y agoIt'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!
- lifeisstillgood 3y agoWhat 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
- skwee357 3y agoThe 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.
- lifeisstillgood 3y agoMy 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).
- throwaway2037 3y agoUgh. 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 3y agoGood 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.
- blitzar 3y ago"Everyone should focus on being an influencer"
- gnz11 3y 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.
- kaechle 3y ago> Sums up 94.7% of the internet. Fixed.
- lysecret 3y agoHahaha I love this community. Every time I read a title like this I am looking for a comment like this ;)
- kaechle 3y agoTrite and rehashed groupthink—marketing garbage at its finest. But you should still write. As should every other human being, vocational identity notwithstanding.
- azangru 3y ago> Each time you write a design review What is this? I've never had to write one.
- kypro 3y agoI'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_lohengramm 3y agoI'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.
- Noumenon72 3y agoI 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.
- kaechle 3y ago
- mold_aid 3y ago"From the dawn of time, people were writing" In conclusion, there are positives and negatives to writing better as an engineer
- castrou 3y 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 3y agoI rarely learned anything meaningful from "X should do Y" types of posts.
- skwee357 3y agoHey! 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 3y agoIs 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_ 3y agoWhile 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.
- skwee357 3y agoInteresting 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 3y agoThe only thing engineers should focus on is, well,engineering.