[HN Gopher] Engineers Need to Write
___________________________________________________________________
Engineers Need to Write
Author : ryanlpeterman
Score : 108 points
Date : 2023-03-24 17:23 UTC (5 hours ago)
(HTM) web link (www.developing.dev)
(TXT) w3m dump (www.developing.dev)
| throwaway138380 wrote:
| The more you write, the more you fight. Why share ideas with
| people who waste your time fighting you.
| touisteur wrote:
| I'll bite. I mostly write for me. Because my memory is
| unperfect, because it shows gaps in my understanding, it forces
| me to gather all the links, resources, references. Because it
| feels so much more concrete than other software/computer
| endeavors.
|
| It's also a great help to _closing_ a topic. Once everything is
| put down and said, I can checkpoint in trust that I 'll be able
| to restore later. Closing all the open loops. For some time at
| least.
|
| And sometimes, most of the times, I end up sharing with
| interested parties. Either because _someone_ needs to write up
| a conclusion or synthesis, and (very humbly) better me than
| someone else, especially if I 'm the one doing or driving most
| of the work.
|
| If you share widely, sometimes it's also a way to find other
| kindred souls, or to have a place to come back 'see, someone
| tried this and it worked'. And to challenge oneself against a
| larger public and see whether you need to improve in some ways.
|
| Just don't look too much at HN or Twitter downers (use the mute
| and block features heavily), try and focus on positive and
| constructive, additive comments. Push back, shut down, leave
| alone anything harmful. It may come with the need for
| additional therapy sessions (it did for me the first times), so
| please beware.
|
| It doesn't need to be a fight. I hope whenever/if you feel like
| writing something and share it, that I'll be able to read it
| and maybe enjoy the thoughtful ideas or conversation or
| inspiration, the challenge.
| sieste wrote:
| During industrialisation the need for physical labour went way
| down because machines did more work. People on the whole moved
| less and this contributed to obesity, osteoporosis etc. Loads of
| gyms, running clubs, etc opened to counteract this trend, to help
| people stay healthy, but also because voluntary physical activity
| is enjoyable.
|
| I think we will see a similar transition happening with writing,
| and perhaps knowledge work in general. The machines do a lot of
| writing for us, and we will have to do less of it. Writing
| becomes more of a pastime activity that people do for pleasure,
| and also to sharpen their thinking and stay sane.
|
| I think we will see an increase in offers for writing retreats,
| journal clubs, calligraphy classes, etc.
| linuxftw wrote:
| I think we'll see long form writing for the average person go
| extinct. 200+ years ago, there was much, much less written by
| the average person, they had no need for it. I suspect we'll
| return to a similar state.
| cjdoc29 wrote:
| Anecdotally, I have found that in doing non-urgent root-cause
| investigations, writing* is the only way for me to think deeply
| about a problem.
|
| My flow looks like:
|
| 1. Write the impact of the problem as currently observed. This
| answers most Product and Executive questions and know I'm
| actively working on solving this problem.
|
| 2. List down ideas of what I think it could be.
|
| 3. Start exploring those ideas by priority.
|
| 4. Bring in Datadog metrics, log items, commands/queries
|
| 5. Have a conclusion for each of those ideas
|
| This has multiplicative effects:
|
| 1. Others don't feel the need to have me in a Zoom call because
| they can follow my progress and comment on the doc if they feel
| strongly about something. I have full focus on the task at hand.
|
| 2. The doc becomes handy in outage review meetings and
| retrospectives later on
|
| 3. Useful commands/queries sometimes end up being formed here and
| I can go back and reuse them
|
| *I rarely actually handwrite things. I depend on Markdown-
| formatted collaborative notes tools that get out of the way (i.e.
| not Google Docs).
| maicro wrote:
| I'll bite - what notes tools do you like to use/recommend? I
| previously used Evernote for everything, but switched to Notion
| a while ago; neither are great at "get[ting] out of the way"
| though I think Evernote was probably better in that regard when
| I used it last...
| cjdoc29 wrote:
| My company uses Dropbox Paper which does a few things well:
| Markdown + embedded images (with captions), and collaborative
| features. I use Notion for my personal stuff, which
| sufficiently gets out of my way, but never tried it with
| other collaborators!
| doubled112 wrote:
| Google Docs is still doable for these kind of collaborative
| notes.
|
| I've learned not to worry about anything that isn't content
| during the process. It can be copied, pasted, formatted, fixed,
| proof read, and put somewhere more permanent later, just not
| while I am hard at it.
| ghaff wrote:
| For collaboration, Google Docs works great. I can't imagine
| going back to a world where mostly everyone took their own
| notes (or not) in meetings. Or a world when editing and
| commenting on a document meant mailing copies around and
| someone often had to merge diffs manually. Going back 10
| years would be a horrible step backward for any sort of
| collaboration in documents.
|
| (and before someone says it, GitHub/GitLab really isn't a
| good substitute because they're designed around a different
| use case. I actually use GitLab for one type of task I'm
| involved with. Given the final form will be an adoc, it's OK
| but not really ideal for writing.)
|
| For personal notes that aren't handwritten, mostly anything
| that will produce a txt file.
| cjdoc29 wrote:
| It's better these days with code block support and now
| accepts Markdown shortcuts. But I haven't given it a chance
| since before those things were supported :)
| ryanlpeterman wrote:
| I do a similar thing. Especially helpful for long-running
| investigations that are difficult to root cause. Documenting
| the current state of the investigation allows people to jump in
| easily and helps everyone tell what the current conclusions
| are.
| hardwaregeek wrote:
| I highly recommend picking up a book in writing and style. I
| enjoyed Dreyer's English (Strunk & White, while commonly
| recommended, is a little antiquated). There are so many avoidable
| mistakes like subject-verb agreement, attaching adjectives to the
| wrong noun ("A violent, intense, affair, Stephen King has written
| another fantastic novel" -> Stephen King is a violent, intense
| affair), and so on.
|
| The classic English teacher advice is also very much worth
| following, such as reading aloud and creating an outline.
|
| And of course, reading is a fantastic way to improve your
| writing. There are examples of great writing in any genre or
| format, but I would say that fiction and long-form journalism are
| usually quite good, while non-fiction books and blog posts tend
| to be more hit or miss. Sometimes you need to read a little James
| Baldwin to remember that writing can be an art form and not just
| a perfunctory means towards an end.
| rmsaksida wrote:
| When hiring, I always pay close attention to a person's writing
| skills. I find it to be a useful heuristic for general software
| engineering competency. But I actually look at this from the
| opposite direction - someone who's good at writing is usually
| also good at reading, and being a good reader is extremely
| helpful in our field. (Good) engineers spend so much time
| reading: technical books, documentation, requirements, specs,
| email, and of course code. Engineers who don't mind reading and
| are able to read attentively tend to be a lot more effective, as
| they will be more knowledgeable and less likely to miss important
| details.
| fnordpiglet wrote:
| I'm a great software engineer but I think by talking not
| writing. I know others that are visual and draw things from I
| think and others that code POCs. Maybe that heuristic is more a
| projection of what you are good at and you look for that in
| others? Maybe having a team with a written word person, a
| visual person, an explanatory person, and a code it first
| person makes a team that can explain what they've written with
| excellent diagramming and a functional POC to demonstrate?
| bavila wrote:
| Where do I find more people like you when I'm job hunting? :)
|
| I used to work as an attorney before getting into software
| engineering, and I clearly took for granted that other educated
| professionals (particular those in a field where precision is
| required) would write clearly, logically, and succinctly. My
| expectations have frequently not been met.
|
| It's particularly humorous, as everyone who has hired me has
| acted like they were taking a big risk because of my non-
| technical background. Yet, each time, they quickly realize it
| was a good idea to hire someone with a strong command of the
| English language and a ruthless attention to detail.
|
| Of course, the technical skills are required as well, but I
| don't think people appreciate how easy those are to pick up for
| someone who is capable of reading and distilling voluminous
| amounts of information in a short period of time.
| quickthrower2 wrote:
| Some of the best people I worked with did something else
| professionally before becoming a software developer. For
| example army, accountants and electronic engineers. They are
| the good all rounders, good at going from ambiguity to decent
| code.
| vsareto wrote:
| >They are the good all rounders, good at going from
| ambiguity to decent code.
|
| That's useful for day-to-day issues, but if you're getting
| a lot of ambiguity that these folks have to address,
| someone higher up needs to write more.
| BurningFrog wrote:
| My theory is that the field has a big population "on the
| spectrum", and they're just not great communicators. Maybe
| because the "theory of mind" deficit.
|
| They do have extra gifts in writing code which compensates
| somewhat. But it's a huge problem when half your team
| struggles to carry a conversation.
| mhluongo wrote:
| Big hiring criterion for us as well! Details in my profile if
| you're looking.
| davnicwil wrote:
| > Engineers who don't mind reading and are able to read
| attentively
|
| One very direct application of this skill in day to day
| engineering is just reading and correctly interpreting error
| logs and stacktraces.
|
| It's pretty incredible how often that's just the cause of a bug
| being literally given verbatim, if one can only engage with the
| message on its terms and frame of reference, and parse out the
| info from it that's meaningful in the context of the software
| you're writing (and not, for instance, expecting the error
| message to somehow do that work for you, which is often
| impossible).
| ryanlpeterman wrote:
| That's a good point, I think Paul Graham has a similar line of
| thinking in the relationship between reading and writing. I
| linked this tweet in my article
| (https://twitter.com/paulg/status/1618747829975130115) but I've
| seen other places he's mentioned something similar as well.
| eikenberry wrote:
| What an odd things to say about software engineering... where
| your job is literally writing. Like telling a newspaper reporter
| that to get better at their job they should write more. I mean
| who would have thought that practicing your craft would improve
| it.
|
| I know the author here is talking about non-code writing but it
| still sounds weird to hear it given that is our job. To write. I
| call myself a writer when people ask what I do as it represents
| it _much_ better than any of the dumb technical names people have
| come up with. No I don 't build houses nor do I design physical
| artifacts. I write.
| conover wrote:
| No one I know associates writing code with writing narrative. I
| would assume you write books if you told me you are a writer.
| eikenberry wrote:
| Not many do. I will alternatively use the work programmer as
| I think it also contains something closer to the idea of what
| we do. But people blank when you tell them that vs. if you
| tell them you are a writer it might spark at least a bit more
| conversation.
| rektide wrote:
| Our org has tools that can look at lines-of-code, number of pull
| requests, etc.
|
| One of the candidate 20% projects that tempts me is something to
| keep track of number of words I write in jira. Or slacking with
| coworkers.
|
| I have great code stats at current job, top tier, but I don't
| think people have the evidence to really see what I really do. I
| write. I make our plans. I review the shit out of our work. I
| help coworkers all the time. (And I write reams of code.)
| reidjs wrote:
| Measuring coding talent by number of lines committed is like
| measuring how good a book is by the number of words in it.
| ElijahLynn wrote:
| Succinct and to the point. Kinda well written in that regard!
| ryanlpeterman wrote:
| Thank you for your kind words :)
| [deleted]
| mtippett wrote:
| For me, it's all about coherent externalization.
|
| Your brain takes shortcuts, you can think you understand what is
| going on, it's only when you need to communicate it you realize
| how many shortcuts in hallucinations of understanding there are
| in your head.
|
| So for those with imgur accounts... I have a challenge for you.
|
| Most people will know how to ride a bike, will know a bike when
| they see it.
|
| But can you communicate what a bike looks like (in a diagram)?
| 90% of you won't be able to.
|
| Grab a piece of paper, and draw a bike. Post it to imgur, and
| post a link to it below (please don't be a troll).
|
| Then take a look at https://www.gianlucagimini.it/portfolio-
| item/velocipedia/
|
| Until you try to communicate a concept or idea in words or
| diagrams, the chances are you are hallucinating your
| understanding.
| xeonmc wrote:
| https://imgur.com/a/A9NwpLk
| fnordpiglet wrote:
| I know folks that control for this by writing a fail fast
| implementation. I do it by talking it through. There's a lot of
| modalities in the human experience and different people are
| adapted to different modalities. Building a strong complete
| team involves covering all the modalities and letting them work
| the way they work best, and as a team. A team that can write,
| speak, draw, produce functional demos, etc, is better than the
| one that can write.
| tstrimple wrote:
| Based on what I saw on that website, only a handful of people
| couldn't draw a bike well enough to get the point across. A few
| more than that posted designs which can't function (fixed front
| wheel), but are easily recognizable as a bike. Most are fine.
| Certainly not supporting that 90% of people won't be able to do
| so. A diagram isn't a spec. It's designed to convey higher
| level ideas of which most of these bike illustrations are fine
| for.
| jxramos wrote:
| they may not even be hallucinations, just short circuit paths
| that have embedded in your conceptualization of stuff that
| they've become unspoken deeply furrowed premises long trusted
| and never thought to be questioned. Surfacing unspoken and
| unwritten premises is something I find exciting, really invites
| getting at the root of stuff.
| HPsquared wrote:
| To write clearly is to think clearly.
| japhyr wrote:
| I think the people who can code well and write good technical
| documentation are going to transition well into the fully AI-
| assisted world. So much of what I'm seeing involves not so much
| the ability to code well, but the ability to write clearly about
| what you want your code to do. I think the people who can write
| decent code but struggle to write good documentation (comments
| and formal docs) are going to struggle to make the transition.
|
| The tools are going to write more and more of the code for us.
| We're going to be spending more time writing about the code and
| less time writing code.
|
| (I posted this as a comment on the article, but there's more
| active conversation here so I pasted it here as well. I'm curious
| if anyone else has thoughts along these lines.)
| abathur wrote:
| A guy at a bar spotted me programming last night and forced a
| conversation on me about an email-processing script ChatGPT
| helped him write, and showed me the conversation on his phone.
|
| It struck me, as a programmer with a creative writing
| background, that he was basically writing microfiction with a
| character (himself) that needed help, and a character (ChatGPT)
| to help him out.
| japhyr wrote:
| How did it work out for him?
| abathur wrote:
| * * *
| qsort wrote:
| I don't see a future where we replace code with natural
| language -- and I'm not only skeptical about it, I know for a
| fact it will never happen: it's an idea that has been tried and
| _did not work_. Formal language is easier, for the same reason
| that nobody in their right mind would rather write "one less
| than the square of the variable" than "x^2 - 1".
|
| I do agree that writing badly is a reliably correlated with
| being a bad developer. Not writing well denotes lack of
| clarity, inattention to detail and self-indulgence, all damning
| attributes for a serious professional.
| ChrisMarshallNY wrote:
| _> Writing your thoughts down forces them into a coherent,
| logical narrative. Condensing your writing gives you a deeper
| understanding. This process improves your thinking._
|
| When I write something down, it changes my viewpoint. Not sure
| why, but it does.
|
| I tend to "just do things a certain way," without really
| planning, structuring, or thinking about it.
|
| I have found that I surprise myself, if I then go back, with a
| goal of explaining what I do, to others.
|
| Here are some examples of what I mean:
|
| [0] https://littlegreenviper.com/miscellany/thats-not-what-
| ships...
|
| [1] https://littlegreenviper.com/various/the-road-most-
| traveled-...
|
| [2] https://littlegreenviper.com/various/evolutionary-design-
| spe...
|
| etc.
|
| [3] https://littlegreenviper.com/miscellany
| GCA10 wrote:
| "Writing doesn't just clarify your existing ideas; it generates
| more of them."
|
| So true! Redrafting and self-editing involves so much more than
| just getting the commas in the right places. This is how we see
| new linkages that weren't obvious at first. It's how we become
| more discerning, so we can define the limits and strengths of our
| concepts more precisely. And it's one of the best ways of opening
| up new avenues of thought. (If A is valid, then B, C and D become
| possible.)
| nanidin wrote:
| My personal version of rubber duck debugging involves writing
| an email to explain the problem. It helps solidify my
| understanding and usually generates new things to follow up on.
| cmason wrote:
| Yes. Very often the email never gets sent -- because I find
| the solution while writing it.
| nextlevelwizard wrote:
| For me it happens in cycles. I get inspiration to jazz-up/re-
| write my blog and that gives me a nudge to write something,
| anything really, just to get to see something new and that gets
| the rock rolling and I end up writing half a dozen posts in few
| weeks. Then I get distracted by some other project or a game or
| whatever and I forget writing for months and when I remember I
| have a blog I feel like I don't have anything "worthy" of
| writing. Until I again get inspiration to start working on the
| code side of the blog again and the cycle beings a new.
| abathur wrote:
| I find reading, writing, and programming can each be incredibly
| generative in their own ways. I haven't _measured_ its
| effectiveness, but I like rotating the intellectual crops, as
| it were. I (at least subjectively) feel most-generative in the
| few weeks after switching from mostly-one to mostly-another.
| lifeisstillgood wrote:
| Writing shows how weak your thinking is - Leslie Lamport
| 123pie123 wrote:
| I'm sure all the people with dyslexia / ADHD would not agree
| crabkin wrote:
| I have ADHD and maybe some sort of low grade dyslexia. My
| voracious curiosity with no regard to structured learning
| or topical coherence has only been a huge boon to my
| reading/writing. I think ADHD/dyslexia has been a bigger
| problem in my math and science classes where I write
| something different than what my brain is thinking, or I
| make arithmetic mistakes. For instance, if I forget to
| write the first noun in a sentence, it isn't as huge a
| problem as when I mix up a summation and summand in an
| answer or on the way to one.
| jxramos wrote:
| fascinating, writing as a generative process. I like it. Think
| about how many tangents show up in text that can't be explored
| fully but can become a subject or book in their own right.
| theturtletalks wrote:
| "Writing about something, even something you know well,
| usually shows you that you didn't know it as well as you
| thought. Putting your ideas into words changes them." [0]
|
| 0. http://www.paulgraham.com/words.html
| mtippett wrote:
| 100%.
|
| Just challenged the hacker news crew to draw a bike. See my
| reply to the OP.
| ryanlpeterman wrote:
| This was a great read, thank you for sharing :)
| briantakita wrote:
| My biggest hang-up wrt writing is prose, specifically maintaining
| & iterating on prose. I would rather write in a graph, but have
| not found any tools which serve my purposes to replace a physical
| notepad in this regard.
|
| Tools like The Brain is ok but I would rather have source files
| which I can commit to a repo. Dendron is ok as well but is not
| universally inteoperable...as I use Jetbrains tooling. I can't
| deny how important the somatic & muscle memory elements are to
| the task of writing & VSCodium is just not on the same level as
| Jetbrains tools.
|
| What would be great is to have a Universal ID & a graph api where
| all of my writings can be queried & updated or amended.
|
| For now, software is more satisfying to write than prose. I hope
| experience of writing in a digital format can become more like
| writing graph data structures in the near future.
| MathMonkeyMan wrote:
| What I'm finding is that writing is good for straightening out
| your ideas, rubber duck style.
|
| As for communication, it depends. One problem with writing is
| that it generates something to read, and people don't want to
| read.
| e_i_pi_2 wrote:
| Definitely agreed - I read my own documentation more than
| anyone else, and writing it out does make for a better system
| design, but I never refer to documentation until I _need_ to
| and I don't expect others to do any differently
| stuckinhell wrote:
| Sure, but the best engineering team in my firm are poor writers.
| I can hire "translators" to write down stuff for them at 1/5 the
| cost.
| fnordpiglet wrote:
| X needs to Y stuff bothers me because it's a "everyone must be
| like me because I'm like me and that's the way things are." I
| gain none of the things the author attributes to writing. I don't
| gain much by drawing pictures either. I do better by thinking a
| lot then talking it through with someone.
|
| I think a better way to think about it is if you have a team,
| there's probably someone on it that gets more done by writing it
| down and another person who does better by drawing it and another
| by coding it and another by talking it through. So, talk it
| through and explain the plan to stakeholders, write it down for
| everyone to have a definite written explanation of what was
| talked about, draw the diagrams to explain in pictures what's
| complex in words, and code a POC to make it real - and do it
| together as a team. don't tell everyone else to be like you,
| enjoy that they are them and they're on your team filling the
| gaps. A sports team isn't composed of uniform cogs, they take
| roles that exploit their natural abilities.
| pxeger1 wrote:
| Instead of "X needs to Y", how about "consider how Y might help
| X". The title is a more succinct, admittedly exaggerated,
| version of what the take-home message should be. It still has a
| point.
| jlengrand wrote:
| The inflation the sales went down so much lately that my local
| supermarket stopped selling m&m's, snickers, mars, kit kat, ....
| They only sell the store brand now.
|
| Was genuinely searching for the the stuff and asked a clerk, they
| said that stuff's gone so pricey people don't buy any more...
| It's honestly a little worrying
|
| https://twitter.com/jlengrand/status/1639340552536686592
| photochemsyn wrote:
| The first question in writing should probably always be: "Who am
| I writing this for?"
|
| A lot of the times, in projects, you're writing to yourself, or
| more precisely to your future self, so that you can figure out in
| the future what it was you were trying to do in the present. If
| you've ever come across one of your past projects, and have no
| idea what it was supposed to do, or where you stopped working on
| it - that's where a document addressed to yourself would have
| been invaluable.
|
| If you're writing for some other audience, then it's most
| important - assuming you want them to read your writing - to try
| to see the world through their eyes. Technical writing should
| generally be gradually incremental, starting from minimal
| assumptions of the audience's knowledge and working upwards.
| Then, they can read along for awhile at least before having to
| jump off the train. I recently came across an excellent example
| of this approach:
|
| https://www.scottaaronson.com/papers/pnp.pdf
|
| As far as non-technical writing, anything goes, be creative, you
| could be the next James Joyce, which AI is unlikely to ever
| replicate, or at least probably not.
| DeathArrow wrote:
| > I hated writing in high school. It wasn't objective like my
| favorite subjects, math and science. It also didn't help that we
| had to write about old, hard-to-understand literature like
| Shakespeare.
|
| While I never considered myself an engineer, but a computer
| scientist, I've always loved writing.
|
| My favorite course in high school beside programming was
| literature and language.
|
| I never stopped writing in a form or another. I love Shakespeare
| as much as I love any other old or new good author.
|
| Considering Shakespeare old and hard to understand doesn't tell
| us as much about Shakespeare as about you.
___________________________________________________________________
(page generated 2023-03-24 23:00 UTC)