17 ms·

Engineers Need to Write

335 points by ryanlpeterman 4y ago

GCA10 4y ago
"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.)
- jxramos 4y ago
  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 4y ago
    "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 http://www.paulgraham.com/words.html
    - mtippett 4y ago
      100%. Just challenged the hacker news crew to draw a bike. See my reply to the OP.
    - ryanlpeterman 4y ago
      This was a great read, thank you for sharing :)
- nextlevelwizard 4y ago
  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 4y ago
  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 4y ago
  Writing shows how weak your thinking is - Leslie Lamport
  - textninja 4y ago
    Writing is thinking
    - dalmo3 4y ago
      ...without relying solely on short term memory.
  - 123pie123 4y ago
    I'm sure all the people with dyslexia / ADHD would not agree
    - crabkin 4y ago
      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.
    - DiggyJohnson 4y ago
      I’m not sure I understand your reasoning, and I’ve been diagnosed with ADHD and am writing a nonfiction book. I understand how this condition might make the writing process more challenging, but I don’t think that contradicts GPs point at all.
    - zwkrt 4y ago
      (This is coming from someone with ADHD but not dyslexia) It's harsh, but it isn't wrong, right? The reason that these states of being are considered 'disorders' is because they interfere with daily life and with tasks that other people consider to be easy. I need to take a lot of time to edit my writing and to re-evaluate the content that I write because it is easy for me to slip into a multi-paragraph tangent. Fundamentally that happens because my thinking is not sharp/focused. On the other hand, when I am done writing I get a feeling of great accomplishment. Like I was able to swim through the deep waters of my mind and harpoon all the good ideas. Being smart isn't worth much if you can't communicate your ideas!
- nanidin 4y ago
  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.
  - carlmr 4y ago
    I started note taking in markdown. I used to note take a lot on paper and it always became a mess. I'm using Obsidian right now for this, although you can just use plain code editor it's nice to have WYSIWYG.
    - oneeyedpigeon 4y ago
      I've just started using obsidian, but only for a subset of my work, to work on individual documents with a very rigid structure. Do you have any tips on taking obsidian to the next level, using it as an integrated tool rather than just a one-off editor?
  - cmason 4y ago
    Yes. Very often the email never gets sent — because I find the solution while writing it.
    - kaashif 4y ago
      This is an incredibly common experience, lots of people I've asked do this. When writing a StackExchange post asking for help, I want to include all relevant information and include a list of things I've tried, along with explanations for why they're dead ends. Writing it all down sometimes helps me realise that one of the ends is in fact not dead.
      - p4l4g4 4y ago
        This happens more often than I'd like to admit. More often it's on work chat or a call, but the principle holds: I try to explain my problem to someone else and while deepening the explanation, I get a face-palm moment (the answer was there all along!), thank the person for its time and franticly start working on the solution. Rubber ducking can be a highly productive measure when your mentally clouded and can take many forms.
- playingalong 4y ago
  So does teaching others.
  - Pokepokalypse 4y ago
    "teaching is the highest form of mastery" -- (don't know who said this quote)
cjdoc29 4y ago
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).
- ryanlpeterman 4y ago
  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.
- maicro 4y ago
  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 4y ago
    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 4y ago
rmsaksida 4y ago
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.
- ryanlpeterman 4y ago
  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 https://twitter.com/paulg/status/1618747829975130115) but I've seen other places he's mentioned something similar as well.
- bavila 4y ago
  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 4y ago
    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.
mtippett 4y ago
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/ 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.
- jxramos 4y ago
  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.
- xeonmc 4y ago
  https://imgur.com/a/A9NwpLk https://imgur.com/a/A9NwpLk
- tstrimple 4y ago
  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.
- fnordpiglet 4y ago
  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.
ChrisMarshallNY 4y ago
> 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-are-built-for/ https://littlegreenviper.com/miscellany/thats-not-what-ships... [1] https://littlegreenviper.com/various/the-road-most-traveled-by/ https://littlegreenviper.com/various/the-road-most-traveled-... [2] https://littlegreenviper.com/various/evolutionary-design-specification/ https://littlegreenviper.com/various/evolutionary-design-spe... etc. [3] https://littlegreenviper.com/miscellany https://littlegreenviper.com/miscellany
throwaway138380 4y ago
The more you write, the more you fight. Why share ideas with people who waste your time fighting you.
- touisteur 4y ago
  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.
  - a_e_k 4y ago
    I love that feeling that I get writing for closure, when I'm distilling and crystallizing things that I've learned about a topic. I use physical notebooks for that kind of writing, and writing the words out by hand once I've understood something just feels so nice and durable. And then I can page it out of my brain, knowing the notes are there if I need them again. (By contrast, I'll usually have a temporary digital file with notes in flux while I'm learning something. But the notebooks are where I write things "on-the-record.")
- naruhodo 4y ago
ElijahLynn 4y ago
Succinct and to the point. Kinda well written in that regard!
- ryanlpeterman 4y ago
  Thank you for your kind words :)
japhyr 4y ago
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 4y ago
  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 4y ago
    How did it work out for him?
    - abathur 4y ago
      He, uh, made the following claims: 1. he's been using it for 9 days 2. he has subscribed for gpt4 3. it took 3 rounds of refining to get it running 4. it did what he wanted 5. it took about 15 minutes to do something that would have taken him "3 months" I believe the first 3 but am skeptical of the last 2. He was, in any case, effusive about its capabilities. For context, I should note: - he was obviously inebriated, high, and the sort of person who trusted a stranger (me) with his unlocked phone while he went to the bathroom. (I think this actually has a little to say about how quickly he's picking up good prompting?) - This was at a dive bar in Houston's east end--not really a tech hub. Edit: he was persuasive enough that I intend to try to shift more of my habitual queries from Google to chat gpt until I at least have a deeper grok of effective prompting than I have picked up so far.
eikenberry 4y ago
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 4y ago
  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 4y ago
    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.
    - naniwaduni 4y ago
      So what you're saying is, essentially, that you've managed to increase engagement by actively misleading people? I'm not sure what to tell you, but congratulations on inventing clickbait for small talk!
deleted 4y ago
[deleted]
HPsquared 4y ago
To write clearly is to think clearly.
briantakita 4y ago
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.
- LegitShady 4y ago
  writing prose is a skill like any other - the more you do it, the better you get at it, the faster and easier it goes. I would outright say doing it without tools is a better learning experience than using tools. A word processor, you, and time are all it takes.
  - briantakita 4y ago
    I hear you & appreciate that prose is an art & craft in itself. Prose, iconography, pictures, spoken word, voice inflection, body language, etc were the only games in town before the advent of computers. Now we have algorithms, graph data structures, set logic, as tools to work with information. Prose can be analyzed using NLP, but it is verbose, full of throwaway words, & the expression of scoped intent of meaning can be improved. One major weakness of prose is the difficulty of gauging breadth & completeness of expression. When writing software, it is easier to perceive if a program is incomplete. Compilers, type systems, automated tests, & runtime errors guard against bugs or issues with syntax or logic. It is more difficult to parse the prose to understand if all of the essential pieces of information (i.e. logical premises followed to their conclusion) is present in the document. If a conversation is started about a document pointing out missing logic or a fallacy, it is difficult to counter a chain of reason other than quoting phrases & responding to those phrases, possibly taking the phrases out of context. There is also a trend toward rivalrous attention dynamics in online conversations. If you look at Hacker News, many of the threads repeat each other & the disagreements quickly turn into bickering. Such patterns of conversation could even be identified with simple algorithms with can be open. A graph data structure allows the context to be transmitted so if a phrase in a graph is quoted, the context comes along with it. If the phrase is separated from the contextual graph, the meaning changes. An assertion or counter assertion could be tested using Set logic. Phrases are less likely to be taken out of context, diminishing strawmen. The full breadth of unique points can also be aggregated. I think tooling with expressions being in a graph would also disincentivize bickering & rivalrous attention dynamics. The cool thing about writing software is that one participates in the trend of evolved tooling of expression. Whether it's writing a library, creating a program or app, writing a language, an experiment of expression is conducted.
sieste 4y ago
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 4y ago
  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.
stuckinhell 4y ago
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.
jlengrand 4y ago
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 https://twitter.com/jlengrand/status/1639340552536686592
rektide 4y ago
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 4y ago
  Measuring coding talent by number of lines committed is like measuring how good a book is by the number of words in it.
  - rektide 4y ago
    I agree, but I also generally am not super opposed to having data. The potential for misuse is very high. But I know I'd rather have it, even though it could mean anything.
fnordpiglet 4y ago
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 4y ago
  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.
  - fnordpiglet 4y ago
    Yes, I agree, it does - if it works for you. if it doesn’t, it doesn’t have a point. But if you read comments on the post you’ll see a lot of folks saying “when I hire I always look at their ability to write” …. This tells me they are writers, writing works for them, this article speaks to them, and they assume it speaks to everyone and anyone it doesn’t can’t possibly be as productive. They assume because it makes them more productive and other modalities don’t that’s the way the world works. This is an incredibly common fallacy, not made of ill will, but it causes all sorts of pain to those who don’t match the hiring managers modality. I know I’m off topic a bit but I think it’s apropos - A good manager looks at the modalities not covered by the team and hires to fill the gaps, but most managers hire to match the modalities they’re familiar with in their own career.
    - 4y ago
hardwaregeek 4y ago
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.
MathMonkeyMan 4y ago
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 4y ago
  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
- ryanlpeterman 4y ago
  Reading is somewhat painful for people if it isn't entertaining. When I write things that are information dense at work, I try my best to condense it to be mindful of people's time. It has worked well for me
photochemsyn 4y ago
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 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.
- ryanlpeterman 4y ago
  +1, knowing your audience is critical
DeathArrow 4y ago
> 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.
moneywoes 4y ago
Any good courses or tangible methods to improve writing besides writing more? It seems as if most of my writing is ent sent straight to dev/null
- ryanlpeterman 4y ago
  I'm currently taking the approach of writing regularly. My thinking is that quantity will lead to quality Also I'm eager to receive feedback on it. That's why I'm so grateful for the Hacker News community's comments!
MobileVet 4y ago
If you want a very short but excellent kick starter for helping yourself become a better writer, I would highly suggest ‘On Writing’ by Stephen King. It was the first things I ever read of his because I don’t like scary stuff. I was so impressed that I have started to read some of his works… and they are amazing. He is such an amazing story teller. Highly recommend picking up ‘On Writing’ and letting it guide you towards a future of improved writing skills via practice and helpful concepts.
- ryanlpeterman 4y ago
  Just picked it up, thanks for the rec! Here's the Amazon link if anyone else is thinking about reading it - https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft/dp/1439156816 https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft...
moystard 4y ago
Writing is undervalued by a lot of software engineers. It is the best medium for sharing information, live (thanks to collaborative documents), but also over time (documentation). An essential skill to develop. I do believe however that fewer and fewer engineers will actually take time to develop that skill and will rely on ChatGPT and co in the future to generate most of the written content based on draft notes.
- ryanlpeterman 4y ago
  Perhaps that will make the engineers that have the skill stand out more. Only time will tell
yawnxyz 4y ago
Do you guys write for yourselves, or write to present ideas to others? I mostly write for myself— that's where ideas get figured out. Most of this happens in an Apple Note or in Notion. I'm apprehensive about all the time I'd be spending polishing something up to put on a blog somewhere, mostly because of the time it takes to explain stuff. We all know that if you take shortcuts and don't speak to a predefined audience, at some point it'll get picked up on HN and torn to shreds...
- ryanlpeterman 4y ago
  Often both. After I write something, it feels like it's a free benefit to also share it with others. I'm grateful the Hacker News community is so giving with feedback (eventhough I've gotten torn to shreds a few times haha)
lfciv 4y ago
People tend to also underestimate the value of humor and pacing in writing. Injecting a little bit of comedy into everything you write (including technical specs) can be incredibly valuable. That being said – it's really hard.
- xena 4y ago
  God yes. Good humor is so hard to do when writing about technical things. I try to get a good balance by judicious application of surrealism, but a lot of the time your jokes won't land, and your references are both too old and too young for your coworkers simultaneously. I try regardless, but it's very hard to avoid accidentally irking coworkers.
- ryanlpeterman 4y ago
  Agreed. The more I write for a public audience, the more I realize that keeping people's attention is hard Humor sounds like a great tool to keep people reading
deterministic 4y ago
Writing down your thoughts and reasoning is a great way to think.
rukuu001 4y ago
Engineers who proactively communicate in any way at all are worth their weight in gold. Writing consistently will certainly improve quality of communication.
gloryjulio 4y ago
I remember that someone mentioned vomit writing and vomit coding a while back in hn. I think it's the same principle. Just write^TM has already made me more productive and more focused
macintux 4y ago
I sat down to write a blog series, a deep dive into configuration of our product at a previous job, and I was amazed at how quickly it exposed the parts of our software that I thought I understood but clearly didn't. As soon as I switched to passive tense, or my brain started to hand wave over something, I knew I'd hit a weak point. And perhaps unsurprisingly, when I'd check with the engineers, as often as not I'd get the same response: "Huh, I'm not sure either." I've never found an equivalent tool for identifying my weaknesses. In a conversation I can bluff my way through something and rationalize it to myself or others as "I don't have all the details at hand but I'm sure I understand it"; when writing, I don't have that same luxury.
- ryanlpeterman 4y ago
  I agree, it’s much easier to hand wave in conversation
justbored123 4y ago
[dead]
tacostakohashi 4y ago
I think I'm decent at writing overall, I did well in English at school, write up documentation which I am able to point other people to, and find I am able to write quick, clear and actionable responses to emails, chats, etc. When it's a topic I have expertise in, and the audience are pretty much my peers, and it's just a matter of accurately describing or summarizing objective facts about the state of the world, some code, some incident, etc, it's not a problem. On the other hand, I really struggle with writing up objectives, performance reviews, intern projects, my own resume, product roadmaps, etc. I tend to put this stuff off to the last minute, and spend way too much time making minor tweaks and edits, but probably not improving the overall impact. I'm never sure how much detail is useful vs just going for vague but impressive sounding bullet points. I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. that more or less live in their own different world, or at least at a different level of abstraction from me. It also doesn't help that it's sporadic stuff that happens once or a few times / year, so I feel I never get good at it or have any kind of feedback loop, and it feels like a distraction from my "actual" coding/day-to-day job, but obviously this stuff actually really important in the long run. I am really tempted to try to hire some kind of communications consultant to basically sit down with me and do this together, or for me, on an hourly basis or something... much like I do for my taxes. Although maybe I should just learn to do it myself, read a few books / youtube on it, etc... in practice, I don't, and if I found someone who was great at it and it got done, maybe I'd have a better job, better projects, etc. Really curious to hear of thoughts on this, whether anyone has ever done something like this, whether it worked out... or if the work to find the right person and explain things exceeded the benefits. It's hard to know if this kind of activity, for me, is a "cost center" that is best outsourced, or a "profit center" that it's a mistake to outsource.
- darkerside 4y ago
  > I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. You seem like a smart person. If you don't understand who is reading it and why, then of course it'll seem like meaningless busy work, and you'll have trouble writing it well. I'd consider telling your manager how you feel, and ask them for help writing these well. Kind of a pair programming session. I bet you'd get a ton out of it.
jrochkind1 4y ago
I enjoy writing good docs, it feels like just another kind of programming to me.
- ryanlpeterman 4y ago
  Same. Coding helps us communicate with machines, writing helps us communicate with each other
jatinarora26 4y ago
Great article! Couldn't agree more! I too have realized that when communicating in the async era, more clarity in writing leads to less wasted time. I re-read my messages when sending them to someone to ensure they are clear.
- ryanlpeterman 4y ago
  Thank you :) Absolutely, collaboration is much smoother if we write well
- zuzuleinen 4y ago
  "I re-read my messages when sending them to someone to ensure they are clear." Kudos for doing that! I hate when people treat writing messages like a second hand skill that doesn't deserve any effort, especially when explaining technical stuff.
Animats 4y ago
Real engineers, who design real physical stuff, need to draw. The people who draw things for design meetings have the most influence.
jillesvangurp 4y ago
I learned to write properly while doing my Ph. D. Basically, if your main job is publishing articles, that is not optional of course. And since English is the dominant language to publish in, I had to learn English as well (my native language is Dutch). An eye opening insight I had while I was learning to write properly was that I was doing a lot of things systematically wrong. So, the job became learning to do it right in a systematic way. This didn't happen overnight but I learned from my mistakes one by one and started criticizing my own writings based on that and slowly improved what I was doing. One by one, I was eliminating whole categories of mistakes and learning why they were mistakes. Another thing that I learned was that putting a lot of effort in writing creates a sunk cost fallacy. You start becoming defensive of all the text you have write. Learning to rewrite your text and stepping over your reluctance to delete stuff you have written is a key skill. Iterating makes things better. It's literally faster to rewrite than to correct text. If it looks or feels wrong, just delete it and write it again. Another insight is that writing things down forces you to make your fuzzy ideas concrete. You get progressive insight from rewriting things that you've already written. This works better if you wait a bit for your short term memory to purge itself of any notions you might have. You can use time to your advantage here. Simply take a break and rewrite or revise what you have written later. Weekends and sleeping are great for this. You come back fresh and you instantly spot all the mistakes you made earlier. People think of writing as an art form. Which of course it is. But in many ways, writing is like programming. It is governed by simple rules (grammar and stylistic ones). All you need to do is learn those rules and apply them. There's a certain logic to how a good text flows. How sentences and paragraphs connect, etc. The whole job of learning to write is figuring out how that works. Tools actually exist that can check your writing automatically these days. Use those and don't argue with them and instead fix the issues that these tools will point out to you and learn about why those are issues that need fixing. Once you stop producing text that has loads of such issues, you'll have become a better writer. It's not that hard. But you do need to make an effort. And of course know to use and install such tools. And since programmers indeed depend on written communication, this is a good skill to have.
blarg1 4y ago
If I have too many ideas floating around my head I will forget some of them. So I write them all down as short bullet points, and skim them when I'm stuck.
hunterbrooks 4y ago
Totally agree - Because I believe in this, I’m spending my time building a GitHub bot that raises Pull Requests from descriptive GitHub issues: https://twitter.com/mrhunterbrooks/status/1639373651010109442?s=46&t=enGYLPkUJTV2FMzYI8Ig6w https://twitter.com/mrhunterbrooks/status/163937365101010944... Clearly written technical specs make implementation easy but also easy to reason about.
asadjb 4y ago
A personal story about how writing helped me make a decision. A few months back, I was job hunting due to tech layoffs and ended up with two offers from different startups. One was a 2-year-old YC company with a larger team, while the other was a brand-new startup where I'd be the first engineer, building the tech stack from the ground up. Deciding between the two was tough, so I tried a creative exercise. I wrote draft emails to both hiring managers, explaining why I chose not to join their startup. After about 90 minutes, my preferences became clear. The only reasons I had for joining the more established startup were job security and better work-life balance. Meanwhile, my passion for the new startup was evident in the email I wrote. This exercise helped me uncover my true feelings. --- It was a very useful exercise; might be able to help someone else faced with this issue.
tomjen3 4y ago
This article did a good job making me want to write more. But it didn't do anything to explain how to write as an engineer. Like the author I didn't enjoy writing in school, so how does writing as an Engineer differ, and how does one improve ones Engineering writing.

335 points by ryanlpeterman 4y ago

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

jxramos 4y ago
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 4y ago
  "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 http://www.paulgraham.com/words.html
  - mtippett 4y ago
    100%. Just challenged the hacker news crew to draw a bike. See my reply to the OP.
  - ryanlpeterman 4y ago
    This was a great read, thank you for sharing :)
nextlevelwizard 4y ago
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 4y ago
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 4y ago
Writing shows how weak your thinking is - Leslie Lamport
- textninja 4y ago
  Writing is thinking
  - dalmo3 4y ago
    ...without relying solely on short term memory.
- 123pie123 4y ago
  I'm sure all the people with dyslexia / ADHD would not agree
  - crabkin 4y ago
    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.
  - DiggyJohnson 4y ago
    I’m not sure I understand your reasoning, and I’ve been diagnosed with ADHD and am writing a nonfiction book. I understand how this condition might make the writing process more challenging, but I don’t think that contradicts GPs point at all.
  - zwkrt 4y ago
    (This is coming from someone with ADHD but not dyslexia) It's harsh, but it isn't wrong, right? The reason that these states of being are considered 'disorders' is because they interfere with daily life and with tasks that other people consider to be easy. I need to take a lot of time to edit my writing and to re-evaluate the content that I write because it is easy for me to slip into a multi-paragraph tangent. Fundamentally that happens because my thinking is not sharp/focused. On the other hand, when I am done writing I get a feeling of great accomplishment. Like I was able to swim through the deep waters of my mind and harpoon all the good ideas. Being smart isn't worth much if you can't communicate your ideas!
nanidin 4y ago
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.
- carlmr 4y ago
  I started note taking in markdown. I used to note take a lot on paper and it always became a mess. I'm using Obsidian right now for this, although you can just use plain code editor it's nice to have WYSIWYG.
  - oneeyedpigeon 4y ago
    I've just started using obsidian, but only for a subset of my work, to work on individual documents with a very rigid structure. Do you have any tips on taking obsidian to the next level, using it as an integrated tool rather than just a one-off editor?
- cmason 4y ago
  Yes. Very often the email never gets sent — because I find the solution while writing it.
  - kaashif 4y ago
    This is an incredibly common experience, lots of people I've asked do this. When writing a StackExchange post asking for help, I want to include all relevant information and include a list of things I've tried, along with explanations for why they're dead ends. Writing it all down sometimes helps me realise that one of the ends is in fact not dead.
    - p4l4g4 4y ago
      This happens more often than I'd like to admit. More often it's on work chat or a call, but the principle holds: I try to explain my problem to someone else and while deepening the explanation, I get a face-palm moment (the answer was there all along!), thank the person for its time and franticly start working on the solution. Rubber ducking can be a highly productive measure when your mentally clouded and can take many forms.
playingalong 4y ago
So does teaching others.
- Pokepokalypse 4y ago
  "teaching is the highest form of mastery" -- (don't know who said this quote)

cjdoc29 4y ago

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

ryanlpeterman 4y ago
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.
maicro 4y ago
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 4y ago
  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 4y ago

rmsaksida 4y ago

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.

ryanlpeterman 4y ago
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 https://twitter.com/paulg/status/1618747829975130115) but I've seen other places he's mentioned something similar as well.
bavila 4y ago
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 4y ago
  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.

mtippett 4y ago

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

jxramos 4y ago
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.
xeonmc 4y ago
https://imgur.com/a/A9NwpLk https://imgur.com/a/A9NwpLk
tstrimple 4y ago
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.
fnordpiglet 4y ago
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.

ChrisMarshallNY 4y ago

> 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-are-built-for/ https://littlegreenviper.com/miscellany/thats-not-what-ships... [1] https://littlegreenviper.com/various/the-road-most-traveled-by/ https://littlegreenviper.com/various/the-road-most-traveled-... [2] https://littlegreenviper.com/various/evolutionary-design-specification/ https://littlegreenviper.com/various/evolutionary-design-spe... etc. [3] https://littlegreenviper.com/miscellany https://littlegreenviper.com/miscellany

throwaway138380 4y ago

The more you write, the more you fight. Why share ideas with people who waste your time fighting you.

touisteur 4y ago
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.
- a_e_k 4y ago
  I love that feeling that I get writing for closure, when I'm distilling and crystallizing things that I've learned about a topic. I use physical notebooks for that kind of writing, and writing the words out by hand once I've understood something just feels so nice and durable. And then I can page it out of my brain, knowing the notes are there if I need them again. (By contrast, I'll usually have a temporary digital file with notes in flux while I'm learning something. But the notebooks are where I write things "on-the-record.")
naruhodo 4y ago

ElijahLynn 4y ago

Succinct and to the point. Kinda well written in that regard!

ryanlpeterman 4y ago
Thank you for your kind words :)

japhyr 4y ago

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 4y ago
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 4y ago
  How did it work out for him?
  - abathur 4y ago
    He, uh, made the following claims: 1. he's been using it for 9 days 2. he has subscribed for gpt4 3. it took 3 rounds of refining to get it running 4. it did what he wanted 5. it took about 15 minutes to do something that would have taken him "3 months" I believe the first 3 but am skeptical of the last 2. He was, in any case, effusive about its capabilities. For context, I should note: - he was obviously inebriated, high, and the sort of person who trusted a stranger (me) with his unlocked phone while he went to the bathroom. (I think this actually has a little to say about how quickly he's picking up good prompting?) - This was at a dive bar in Houston's east end--not really a tech hub. Edit: he was persuasive enough that I intend to try to shift more of my habitual queries from Google to chat gpt until I at least have a deeper grok of effective prompting than I have picked up so far.

eikenberry 4y ago

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 4y ago
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 4y ago
  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.
  - naniwaduni 4y ago
    So what you're saying is, essentially, that you've managed to increase engagement by actively misleading people? I'm not sure what to tell you, but congratulations on inventing clickbait for small talk!

deleted 4y ago

[deleted]

HPsquared 4y ago

To write clearly is to think clearly.

briantakita 4y ago

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.

LegitShady 4y ago
writing prose is a skill like any other - the more you do it, the better you get at it, the faster and easier it goes. I would outright say doing it without tools is a better learning experience than using tools. A word processor, you, and time are all it takes.
- briantakita 4y ago
  I hear you & appreciate that prose is an art & craft in itself. Prose, iconography, pictures, spoken word, voice inflection, body language, etc were the only games in town before the advent of computers. Now we have algorithms, graph data structures, set logic, as tools to work with information. Prose can be analyzed using NLP, but it is verbose, full of throwaway words, & the expression of scoped intent of meaning can be improved. One major weakness of prose is the difficulty of gauging breadth & completeness of expression. When writing software, it is easier to perceive if a program is incomplete. Compilers, type systems, automated tests, & runtime errors guard against bugs or issues with syntax or logic. It is more difficult to parse the prose to understand if all of the essential pieces of information (i.e. logical premises followed to their conclusion) is present in the document. If a conversation is started about a document pointing out missing logic or a fallacy, it is difficult to counter a chain of reason other than quoting phrases & responding to those phrases, possibly taking the phrases out of context. There is also a trend toward rivalrous attention dynamics in online conversations. If you look at Hacker News, many of the threads repeat each other & the disagreements quickly turn into bickering. Such patterns of conversation could even be identified with simple algorithms with can be open. A graph data structure allows the context to be transmitted so if a phrase in a graph is quoted, the context comes along with it. If the phrase is separated from the contextual graph, the meaning changes. An assertion or counter assertion could be tested using Set logic. Phrases are less likely to be taken out of context, diminishing strawmen. The full breadth of unique points can also be aggregated. I think tooling with expressions being in a graph would also disincentivize bickering & rivalrous attention dynamics. The cool thing about writing software is that one participates in the trend of evolved tooling of expression. Whether it's writing a library, creating a program or app, writing a language, an experiment of expression is conducted.

sieste 4y ago

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 4y ago
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.

stuckinhell 4y ago

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.

jlengrand 4y ago

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 https://twitter.com/jlengrand/status/1639340552536686592

rektide 4y ago

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 4y ago
Measuring coding talent by number of lines committed is like measuring how good a book is by the number of words in it.
- rektide 4y ago
  I agree, but I also generally am not super opposed to having data. The potential for misuse is very high. But I know I'd rather have it, even though it could mean anything.

fnordpiglet 4y ago

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 4y ago
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.
- fnordpiglet 4y ago
  Yes, I agree, it does - if it works for you. if it doesn’t, it doesn’t have a point. But if you read comments on the post you’ll see a lot of folks saying “when I hire I always look at their ability to write” …. This tells me they are writers, writing works for them, this article speaks to them, and they assume it speaks to everyone and anyone it doesn’t can’t possibly be as productive. They assume because it makes them more productive and other modalities don’t that’s the way the world works. This is an incredibly common fallacy, not made of ill will, but it causes all sorts of pain to those who don’t match the hiring managers modality. I know I’m off topic a bit but I think it’s apropos - A good manager looks at the modalities not covered by the team and hires to fill the gaps, but most managers hire to match the modalities they’re familiar with in their own career.
  - 4y ago

hardwaregeek 4y ago

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.

MathMonkeyMan 4y ago

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 4y ago
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
ryanlpeterman 4y ago
Reading is somewhat painful for people if it isn't entertaining. When I write things that are information dense at work, I try my best to condense it to be mindful of people's time. It has worked well for me

photochemsyn 4y ago

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

ryanlpeterman 4y ago
+1, knowing your audience is critical

DeathArrow 4y ago

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

moneywoes 4y ago

Any good courses or tangible methods to improve writing besides writing more? It seems as if most of my writing is ent sent straight to dev/null

ryanlpeterman 4y ago
I'm currently taking the approach of writing regularly. My thinking is that quantity will lead to quality Also I'm eager to receive feedback on it. That's why I'm so grateful for the Hacker News community's comments!

MobileVet 4y ago

If you want a very short but excellent kick starter for helping yourself become a better writer, I would highly suggest ‘On Writing’ by Stephen King. It was the first things I ever read of his because I don’t like scary stuff. I was so impressed that I have started to read some of his works… and they are amazing. He is such an amazing story teller. Highly recommend picking up ‘On Writing’ and letting it guide you towards a future of improved writing skills via practice and helpful concepts.

ryanlpeterman 4y ago
Just picked it up, thanks for the rec! Here's the Amazon link if anyone else is thinking about reading it - https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft/dp/1439156816 https://www.amazon.com/Writing-10th-Anniversary-Memoir-Craft...

moystard 4y ago

Writing is undervalued by a lot of software engineers. It is the best medium for sharing information, live (thanks to collaborative documents), but also over time (documentation). An essential skill to develop. I do believe however that fewer and fewer engineers will actually take time to develop that skill and will rely on ChatGPT and co in the future to generate most of the written content based on draft notes.

ryanlpeterman 4y ago
Perhaps that will make the engineers that have the skill stand out more. Only time will tell

yawnxyz 4y ago

Do you guys write for yourselves, or write to present ideas to others? I mostly write for myself— that's where ideas get figured out. Most of this happens in an Apple Note or in Notion. I'm apprehensive about all the time I'd be spending polishing something up to put on a blog somewhere, mostly because of the time it takes to explain stuff. We all know that if you take shortcuts and don't speak to a predefined audience, at some point it'll get picked up on HN and torn to shreds...

ryanlpeterman 4y ago
Often both. After I write something, it feels like it's a free benefit to also share it with others. I'm grateful the Hacker News community is so giving with feedback (eventhough I've gotten torn to shreds a few times haha)

lfciv 4y ago

People tend to also underestimate the value of humor and pacing in writing. Injecting a little bit of comedy into everything you write (including technical specs) can be incredibly valuable. That being said – it's really hard.

xena 4y ago
God yes. Good humor is so hard to do when writing about technical things. I try to get a good balance by judicious application of surrealism, but a lot of the time your jokes won't land, and your references are both too old and too young for your coworkers simultaneously. I try regardless, but it's very hard to avoid accidentally irking coworkers.
ryanlpeterman 4y ago
Agreed. The more I write for a public audience, the more I realize that keeping people's attention is hard Humor sounds like a great tool to keep people reading

deterministic 4y ago

Writing down your thoughts and reasoning is a great way to think.

rukuu001 4y ago

Engineers who proactively communicate in any way at all are worth their weight in gold. Writing consistently will certainly improve quality of communication.

gloryjulio 4y ago

I remember that someone mentioned vomit writing and vomit coding a while back in hn. I think it's the same principle. Just write^TM has already made me more productive and more focused

macintux 4y ago

I sat down to write a blog series, a deep dive into configuration of our product at a previous job, and I was amazed at how quickly it exposed the parts of our software that I thought I understood but clearly didn't. As soon as I switched to passive tense, or my brain started to hand wave over something, I knew I'd hit a weak point. And perhaps unsurprisingly, when I'd check with the engineers, as often as not I'd get the same response: "Huh, I'm not sure either." I've never found an equivalent tool for identifying my weaknesses. In a conversation I can bluff my way through something and rationalize it to myself or others as "I don't have all the details at hand but I'm sure I understand it"; when writing, I don't have that same luxury.

ryanlpeterman 4y ago
I agree, it’s much easier to hand wave in conversation

justbored123 4y ago

[dead]

tacostakohashi 4y ago

I think I'm decent at writing overall, I did well in English at school, write up documentation which I am able to point other people to, and find I am able to write quick, clear and actionable responses to emails, chats, etc. When it's a topic I have expertise in, and the audience are pretty much my peers, and it's just a matter of accurately describing or summarizing objective facts about the state of the world, some code, some incident, etc, it's not a problem. On the other hand, I really struggle with writing up objectives, performance reviews, intern projects, my own resume, product roadmaps, etc. I tend to put this stuff off to the last minute, and spend way too much time making minor tweaks and edits, but probably not improving the overall impact. I'm never sure how much detail is useful vs just going for vague but impressive sounding bullet points. I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. that more or less live in their own different world, or at least at a different level of abstraction from me. It also doesn't help that it's sporadic stuff that happens once or a few times / year, so I feel I never get good at it or have any kind of feedback loop, and it feels like a distraction from my "actual" coding/day-to-day job, but obviously this stuff actually really important in the long run. I am really tempted to try to hire some kind of communications consultant to basically sit down with me and do this together, or for me, on an hourly basis or something... much like I do for my taxes. Although maybe I should just learn to do it myself, read a few books / youtube on it, etc... in practice, I don't, and if I found someone who was great at it and it got done, maybe I'd have a better job, better projects, etc. Really curious to hear of thoughts on this, whether anyone has ever done something like this, whether it worked out... or if the work to find the right person and explain things exceeded the benefits. It's hard to know if this kind of activity, for me, is a "cost center" that is best outsourced, or a "profit center" that it's a mistake to outsource.

darkerside 4y ago
> I guess these things are basically marketing / advertising / BS, and the audience is senior management, hiring managers, clients, etc. You seem like a smart person. If you don't understand who is reading it and why, then of course it'll seem like meaningless busy work, and you'll have trouble writing it well. I'd consider telling your manager how you feel, and ask them for help writing these well. Kind of a pair programming session. I bet you'd get a ton out of it.

jrochkind1 4y ago

I enjoy writing good docs, it feels like just another kind of programming to me.

ryanlpeterman 4y ago
Same. Coding helps us communicate with machines, writing helps us communicate with each other

jatinarora26 4y ago

Great article! Couldn't agree more! I too have realized that when communicating in the async era, more clarity in writing leads to less wasted time. I re-read my messages when sending them to someone to ensure they are clear.

ryanlpeterman 4y ago
Thank you :) Absolutely, collaboration is much smoother if we write well
zuzuleinen 4y ago
"I re-read my messages when sending them to someone to ensure they are clear." Kudos for doing that! I hate when people treat writing messages like a second hand skill that doesn't deserve any effort, especially when explaining technical stuff.

Animats 4y ago

Real engineers, who design real physical stuff, need to draw. The people who draw things for design meetings have the most influence.

jillesvangurp 4y ago

I learned to write properly while doing my Ph. D. Basically, if your main job is publishing articles, that is not optional of course. And since English is the dominant language to publish in, I had to learn English as well (my native language is Dutch). An eye opening insight I had while I was learning to write properly was that I was doing a lot of things systematically wrong. So, the job became learning to do it right in a systematic way. This didn't happen overnight but I learned from my mistakes one by one and started criticizing my own writings based on that and slowly improved what I was doing. One by one, I was eliminating whole categories of mistakes and learning why they were mistakes. Another thing that I learned was that putting a lot of effort in writing creates a sunk cost fallacy. You start becoming defensive of all the text you have write. Learning to rewrite your text and stepping over your reluctance to delete stuff you have written is a key skill. Iterating makes things better. It's literally faster to rewrite than to correct text. If it looks or feels wrong, just delete it and write it again. Another insight is that writing things down forces you to make your fuzzy ideas concrete. You get progressive insight from rewriting things that you've already written. This works better if you wait a bit for your short term memory to purge itself of any notions you might have. You can use time to your advantage here. Simply take a break and rewrite or revise what you have written later. Weekends and sleeping are great for this. You come back fresh and you instantly spot all the mistakes you made earlier. People think of writing as an art form. Which of course it is. But in many ways, writing is like programming. It is governed by simple rules (grammar and stylistic ones). All you need to do is learn those rules and apply them. There's a certain logic to how a good text flows. How sentences and paragraphs connect, etc. The whole job of learning to write is figuring out how that works. Tools actually exist that can check your writing automatically these days. Use those and don't argue with them and instead fix the issues that these tools will point out to you and learn about why those are issues that need fixing. Once you stop producing text that has loads of such issues, you'll have become a better writer. It's not that hard. But you do need to make an effort. And of course know to use and install such tools. And since programmers indeed depend on written communication, this is a good skill to have.

blarg1 4y ago

If I have too many ideas floating around my head I will forget some of them. So I write them all down as short bullet points, and skim them when I'm stuck.

hunterbrooks 4y ago

Totally agree - Because I believe in this, I’m spending my time building a GitHub bot that raises Pull Requests from descriptive GitHub issues: https://twitter.com/mrhunterbrooks/status/1639373651010109442?s=46&t=enGYLPkUJTV2FMzYI8Ig6w https://twitter.com/mrhunterbrooks/status/163937365101010944... Clearly written technical specs make implementation easy but also easy to reason about.

asadjb 4y ago

A personal story about how writing helped me make a decision. A few months back, I was job hunting due to tech layoffs and ended up with two offers from different startups. One was a 2-year-old YC company with a larger team, while the other was a brand-new startup where I'd be the first engineer, building the tech stack from the ground up. Deciding between the two was tough, so I tried a creative exercise. I wrote draft emails to both hiring managers, explaining why I chose not to join their startup. After about 90 minutes, my preferences became clear. The only reasons I had for joining the more established startup were job security and better work-life balance. Meanwhile, my passion for the new startup was evident in the email I wrote. This exercise helped me uncover my true feelings. --- It was a very useful exercise; might be able to help someone else faced with this issue.

tomjen3 4y ago

This article did a good job making me want to write more. But it didn't do anything to explain how to write as an engineer. Like the author I didn't enjoy writing in school, so how does writing as an Engineer differ, and how does one improve ones Engineering writing.