Here's what I wrote... https://www.evalapply.org/posts/writing-maketh-the-10x-developer/

Anyone got some favourite reasons? Some usual suspects are "it's too much work", "it's too boring", "code is truth", "what's in it for me?".

Writing is a powerful skill, writing down & documenting all your processes can make it so painless to answer questions and unblock your teammates when they hit blockers

Writing is a form of expressing oneself in writing. I'd force most programmers to undergo a creative programming workshop. That skill's sorely lacking and it shows

Why then do so many developers rebel at the thought of writing?

Because they're bad at it. No one likes sucking. It hurts, mentally, especially when they're supposedly good at something else

Another reason, that used to be a part of me, is thinking that it's a waste of time. "I'll remember that", "there's git log" (that I used scantily before as well), "there's bash history", etc. And plain laziness on top: "Documenting the commands that need to be run means writing them down again right after I wrote them to be executed - that's just twice the work."

Because they're bad at it.Is it a consequence of misplaced --- and unsaid --- expectations? An assumption that one must write like a writer (which is really hard and almost everyone sucks by definition), when all we need to be is the average high school freshman?

I'm not bad at writing but I think I'm quite lazy. I also feel discouraged by LLMs and their content generation. Recent lawsuits have shown that LLM model authors take content for free and provide them without contribution or consent. Why would I want to participate in this content economy that won't even pay? Also recent job market has shown that nobody cares about people. So why would they care about one or two blog posts? I also don't have twitters and facebooks because they are simply misinformation machines and privacy disasters.

How would any LLM gets its hands on your personal notes or a README/Wiki in your company's project? And even if it does - so what? Writing here is not meant to be directly converted to money. > Also recent job market has shown that nobody cares about people. So why would they care about one or two blog posts? There's no "they". There's you, your colleagues, your fellow chat residents, any company that you might be interested in getting into, and so on. The "they" here is so diverse that the concept of "them" is barely meaningful.

I see. If the focus is about writing documentation documents then I don't have any objections. It's part of the job. Yes, this is less likely to end up in a training set but most of the time the company has an incentive to not publicize it. For the different case where the company wants to find a suitable candidate and the current public materials from that person are not enough then I don't see how writing specifically would contribute to the decisions. Of course -- if there is no content then writing would help. But if there are other things then why would writing help more than a large project? Chat residents -- Yes, i didn't post much. Maybe in the future. Not sure.

I wasn't thinking about documentation, but code. Your ability to organize your thoughts and express them in writing is equally expressed in code and prose.

> But if there are other things then why would writing help more than a large project? Because it's harder to gauge a large project as compared to an article or even a series of articles. And even after having spent quite some time on checking someone's project, unless you're in the know, all you'd be able to tell is "well, it works and this project is of this scale, so at least the person can write a project of that scale that works". After reading a few articles, you'd be able to say "this person knows what they're talking about". I've experienced it second-hand during a call with a client where he went through some other contractors he hired and all the reasons for why he hired them. Code was brought up only once, and only in the "so this exists" manner. But articles and conference videos were given much more thought.

Non-public, at-workplace developerly writing is the object of my interest here (code comments, reviews, function docstrings, READMEs, rationales, design docs, commit messages etc.). This is not a place for masterful literature, but simple high-school text that clarifies and organises thought. Places that use this kind of writing well tend to be very good professional environments. They tend to have smaller teams delivering lots of productive output, while working sane hours. Staff satisfaction tends to be good. Attrition low. Bus factor low. Agility high. So why isn't good workplace writing the norm? Why do people resist it?

In the Clojure community, I love how griffin says it. Their "How we write" page is remarkable. How we write https://griffin.com/how-we-write Good writing is the single most undervalued talent a startup can have. I agree 100%!

Writing doesn't come naturally to me, but I've tried a lot and improved. It sometimes helps me organise and communicate my thoughts. But I dislike the idea of it being a requirement for development. Sure, when I made my own libraries I made sure to document them, which had value, but the real skill - and fun - is in making the system. Writing was one particular way for me to organise my thoughts, but it wasn't necessary. Sometimes just thinking about it long enough does the trick. Code keeps me honest in a way that writing does it - it has to compile and produce the right results. When you're writing, you can magic things into existence. Most writing is like this. I'm not convinced that writing ability is a strong proxy for development ability. It's just one medium that some people prefer and others don't, with some transfer into other domains. It would be like saying that chess is an underrated skill because it teaches patience and coming up with strategies that work against someone trying to defeat you. Maybe it does a little, but it's not something I would ask about in a job interview.

Could you illustrate what you mean by writing ability? Maybe I imagine it differently.

When you're writing, you can magic things into existence. Most writing is like this.For example, my purpose is to do just the opposite... viz. to weed out magical thinking (do on-paper tradeoffs, napkin math, skeleton api designs etc.).

I'm using writing ability as a sort of catch-all term that encompasses the skills to write in different formats - documentation, tutorials, articles/essays, etc, and write in a way that people can read while conveying the intended message. Without writing ability, the idea might be good, but people don't understand it - in the written form at least. Maybe someone has better luck speaking. It's also possible to write well to communicate falsities and use rhetorical tricks to persuade people. The ways you mention to weed out magical thinking are good, but I wouldn't count them as writing because you can do it elsewhere

That said - I am curious about the idea of replacing meetings and presentations with writing that people read ahead of time, rather than respond to on the spot, maybe that can lead to better decisions, and maybe that's a reason to expect people to write more

ah, I'll bite, actually because I am also a profound fan of writing and basically agree with the conclusion. however, it would be fair to contextualize the premises better. there's some survivor and selection bias in the 10x article: for every influential K&R book, there must be countless inconsequential works of writing. on the flipside of writing, there is reading, and I have read plenty of wasted ink. "modern civilization" is built as much on less traceable non-writing work, like care work, maintenance work and even avoided work (ironically less traceable because of the lack of record, but no less worthy). there are many social/cultural/subcultural groups in the world for whom writing isn't normative, at no loss. relatedly, it's also questionable how much "modern civilization" (depending on what it means) is even aspirational—maybe we need less of some kinds of writing. my personal experience as a self-identified failed writer is mostly frustration. not so much with writing, as with two particular aspects: editing, and scoping. editing often involves loss in disposing of drafts and words, and loss aversion kicks in. scoping almost always triggers a feeling of diving in too deep, biting off too much, or getting daunted by finding out how much known-unknown there is. so as a fan of writing, sometimes disdain writing. nowadays, I spend a lot of time on the thinking part of writing (hammock time) without actually transcribing. it's less effective but often good enough.

It seems that the above comment doesn't take into account this part from a comment from the author: > Non-public, at-workplace developerly writing is the object of my interest here (code comments, reviews, function docstrings, READMEs, rationales, design docs, commit messages etc.)

> It seems that the above comment doesn't take into account this part from a comment from the author: if that refers to my comment, I was initially addressing the premises of the linked article which goes beyond that limit. but the argument seems to be the same: to write consequential if not literary works albeit in a narrower non-public context. but ink can be wasted in public or private. non-writing contributions can be worthy in public or private. editing and scoping can be difficult in public or private. I think it does take the object of interest into account.

I'd love to be better at writing, but I'm terrible. I don't know why. I can know what I want to say in my head, but there is a mental block that appears that makes it so hard to translate what's in my head into words. 😕

There are writing exercises just for that

My thoughts are could it be because writing is a bit more fuzzy, you can string words together into sentences but you have to choose from so many options, finding words that work well together is difficult especially if you want to write some thing engaging that other will want to read.

I know my own writing is very dry and not very creative which makes anything I write a bore to read so I will avoid writing things 😕

When it's about docs, it's better to be dry than silent. Maybe even better than overly eloquent, especially if the team has or can have people for whom English is not the first language.

I think in a professional environment, depending on environments someone has worked in in the past, it may seem like a waste of effort compared to how much work it takes to produce something versus how much effort people are going to spend on consuming it and actually using it.

Yes, I think path dependence is definitely a factor.

As m'colleague and friend @U052TCFJH astutely remarked: > You can write because of process, or because of culture. If it is by process, then your leadership does not write.

@UMY8HG1HR I hear you about survivorship bias. In the post I was trying to sketch out the spectrum of writerly effect, and side-by-side suggesting that those examples are not outliers. Also, I think this whole idea of 10x-ing is relative. There are no sensible absolutes in this picture. Especially in our business of thought-stuff, a person or team can hope to leverage themselves a lot, with common-sense writing and ways to make it useful. All this, done in-house, with the aim of forfending rework, reducing bus factor, freeing up brain cycles, keeping velocity and throughput high as complexity grows etc.

As a small real example, I'm talking about simple things such as: • explanatory in-line comments in source, e.g.: https://github.com/adityaathalye/shite/tree/master/bin • a half-decent commit history. e.g. https://github.com/adityaathalye/shite/commits/master/ • project documentation that explains the design (ignore the extra animations, any literary flair etc. ... just look at the structure and topic coverage of the content). e.g. https://github.com/adityaathalye/shite/blob/master/README.md

At this point, even git log | grep type stuff can become surprisingly useful. I often quickstart documentation for features and projects by catenating a bunch of commit messages and organising / cleaning them up. I rarely face a "blank page" problem here (though it remains a thorn in the side of my writer's blog :D). I think the little constructive things can add up pretty fast into big constructive things. The hard bit is creating the culture where this sort of thing can work (as in provide a lot of immediate + sustained value) as an everyday practice.

@U02DXJUS5JA I'll take your self-described "dry and boring" any day, in your commits and docstrings and readmes. Here, only clarity and sufficiency truly matter.

I don't disdain writing -- I know it's important -- but I'm very, very slow at writing anything long form and my experiences suggest most of my colleagues over the decades tend not to read anything long form anyway. So I'm happy to write docstrings and comments. Writing good ones takes practice (and feedback). I've had a lot of colleagues over the years that just don't write docstrings and comments and, where I've had the power of review, I've made them go back and either improve the code so it is crystal clear what it is doing and why or add sufficient docstrings and/or comments to make the murky code clear enough. In one of my first jobs, I wrote a full-screen text editor (in assembler) that interfaced with insurance policy systems. I had to write documentation for both developers and users. It was so poor that after I moved on, they had to hire a professional tech writer to rewrite it all 😞 Over the years, I've worked hard to improve -- because I understand it is important! -- but I've never had training on this skill at any company at which I've worked. I've just taken onboard feedback from the various "readers" of my writing -- and I'm still learning and improving (after 40+ years of doing this). At school, I was in the bottom stream for English (at an English "Grammar School") and barely passed my O-level English Language course (exams taken at age 16 -- think Harry Potter and OWLs: Ordinary Wizarding Level exams) and I scored "unclassified" on my English Literature course -- a failure so bad that you don't even get a certificate saying you failed! Those were the last English courses I ever took. For my A-levels (Advanced Wizarding Level exams, taken at age 18), I studied only Mathematics, Advanced Mathematics, and German(!). At university, I studied only Mathematics and Computer Science -- British universities have no requirements for students to take a mix of classes like US universities do. I stayed on for three years PhD research (into functional programming language design and implementation) but ultimately never wrote it up -- partly because I hated the labor of writing. When I worked at Macromedia in the early aughts, my manager was very enamored of the then-new explosion of blogs and asked every team member to start a technical blog. I set an alarm for 10:30 am every work day and wrote a post for several years. Some were short -- just an interesting link and a sentence of commentary -- some were essays. Over time, an with public feedback, my writing slowly improved, and it is that (initially forced) blogging that I credit with the (passable) writing skills I have today. So, TL;DR: developers don't write because we don't make them write, and because they don't write, they don't get good at it, so they never come to enjoy it. We should force developers to write more (more often and more long form pieces).

> I'm very, very slow at writing anything long form Proceeds to write the longest message in the thread with a tl;dr. :D

(you've no idea how long it took me! 🙂 )

Why young engineers hate / disdain writing 1. Lack of a quick gratification. Writing pays off in the long run. 2. Lack of structure. When contributing to code a young engineer is mostly adding something or modifying it. Starting something from scratch is still daunting for a new engineer. Same applies for writing. A blank page is a writer’s biggest fear. 3. Lack of knowledge of what good writing looks like. What one should aspire for. It’s too overwhelming.

I can say from my experience: developing a complex system from scratch over a year and a half (of the same system, not extra layers or features or whatever, just getting the initial idea right) absolutely HAD to incorporate A LOT of writing. Every little design decision that wasn't written down was paid for (with tail chaising) until written down. It was an enabler to analyze and "nail" different parts and possibilities of the system concurrently. Basically allowing about a dozen developers (all of them are me over the months) communicate without being in the same place at the same time. The writing was somewhat structured, but it was my structure (an outline of short bullet points), and if I was to publish it, I'm guessing not many would be able to follow along. But it allowed me to develop that system quite successfully, and from time to time explain to my colleagues how different parts work (most of them couldn't keep that understanding for long). In conclusion: I'm pretty sure not many could develop that kind of complexity keeping and analyzing all the details in their head, I'm sure as hell I couldn't. So from my experience, there's a threshold of complexity that requires you to augment your thought process with some medium, for me it was writing (and some charting).

The counterpart of this that probably finally answers this thread's original question is: In our team / company, people that don't feel like they're doing some complex or critical analysis of something (that requires writing), don't write. If they feel like they can just code it that's what they're doing. I do feel it's curbing the potential depth of the work and understanding of the problem solved and its solution space.

don’t mind me, just stopping by to paste in this bit from an https://www.thebeliever.net/an-interview-with-ted-chiang/: > BLVR: You got a bachelor’s degree in computer science. Do you ever see the work of creating a story to be analogous to an engineering process? > > TC: I don’t see the two as being that closely aligned. What I would say is that the closest connection between my fiction and my day job of technical writing is that a good explanation can be a beautiful thing. So I am interested in clarity, in helping a reader to understand concepts, in both technical writing and fiction writing. The techniques involved are radically different, but my goals are similar, in that in both cases I’m trying to get an idea across, and I think a lot about what’s the best way to do that.

I enjoy writing about technical topics, but I find myself reluctant to pour a bunch of energy into documentation, tutorials, etc. This bit from Sean above resonates: “my experiences suggest most of my colleagues over the decades tend not to read anything long form anyway” I do more just-in-time writing because I’ve found most just-in-case writing to be wasted effort. Too much time in academia, teaching classes and writing support materials, tech support, tech marketing and sales, product, client discussions, etc. — write all you want, it’s mostly into the void, because people just don’t read things. I will add the caveat that there are many exceptions, e.g. writing parts of the design or contract or tutorial/quickstart material is a good way to organize my thoughts and provide myself with feedback about whether or not I’m taking the right approach with the software side of things.

And toward one of the other points, I do try to push discussions of any complexity on meetings into doc or sheet form, taking things out of people’s heads and into writing that everyone can look at together ASAP.

I routinely underestimate the power of writing to distill and clarify my thoughts when working through a programming problem, even though I got good at writing prose before writing a single line of code. I benefited a lot in my studies from Jim Pryor’s guide on http://www.jimpryor.net/teaching/guidelines/writing.html. While philosophy might not seem like the most relevant field for technical writing, a central aspect is making an argument for a particular case. If you want to justify why a particular approach is the best one, and give fair and complete consideration to alternative approaches to the same problem, this advice is a good starting point. Philosophy aspires to be both precise and concise when done well, two qualities that also help in technical writing.

I will also say that writing is beneficial even if nobody reads it, because https://www.goodreads.com/quotes/160127-i-have-to-write-to-discover-what-i-am-doing

I’m a strong skeptic of “writing is thinking,” both are different and helpful activities, and one or the other might be appropriate at the time. the type of writing that helps the author is quite often not the same as the writing that helps the reader. and, well, for the latter point, there’s a reason we say hammock driven development and not notebook driven development. And on the other side of the extremes, “no plan survives contact with the enemy,” where ‘the enemy’ is seldom ‘getting the thing written down clearly.’ But the same sentiment is clearly what’s behind “working software over comprehensive documentation.”

you’ll also note that professional writers don’t tend to spend much time fighting about whether plotters are better than pantsers. people have brains that work in different ways.

“… the enemy is seldom ‘getting the thing written down clearly.’” I envy the professional environments you’ve worked in! I cannot say the same of many places where I’ve worked. Underspecified, unclear requirements, insufficiently documented expectations not communicated clearly in the written form are perennial sources of friction in my experience, especially when it comes to the boundary between programmers and non-programmers in the organization. To offer another military cliché as a rejoinder: “I’ve found that plans are useless, but planning is indispensable.” In my view, writing is frequently the “planning,” even if the written artifact ultimately goes the way of the “plan.”

yes, that’s been a problem at places, but context here is key — I mean enemy in the context of the plan not surviving. the failure to formulate a plan is seldom solved by writing about it in a vacuum. often there’s a lack of alignment, and a lot of wrong belief (of the FUD variety) that can be dispelled quickly by getting everyone to suspend judgment long enough to try a few different things out.

I think writing is valuable but it’s only one valuable activity among many and I personally prefer not to see it enshrined. Anytime something starts getting thrown around as some unambiguous good practice, I immediately imagine myself working at a place that injects that thing into its process everywhere it can.

because that’s what tends to happen. And this whole writing about all the things to refine your thinking idea is… well, I consulted at a place once where the architects outnumbered the developers by a good margin, and it sounds a lot like that place 🙂

@U051MHSEK > I hear you about survivorship bias. In the post I was trying to sketch out the spectrum of writerly effect, and side-by-side suggesting that those examples are not outliers. so correlated along the spectrum of writerly effect is writerly waste, the survivor effect scales down in correlation too. > Especially in our business of thought-stuff, a person or team can hope to leverage themselves a lot, with common-sense writing and ways to make it useful. this is just it, there are multiple ways to develop leverage, not all of which are writing, and many people seem to do well specializing their effort in those non-writing ways. I have a hard time persuading them to change, even if I took to writing myself.

and yes, of course on the other end of the spectrum there are places where all the devs were slinging code around the clock and no one had figured out who their customers were, what they wanted, and how they were going to make enough money to pay for all the code slinging. I am not against writing--again, it’s helpful in many situations. figuring out which tool to reach for in a given situation is the whole game, and writing is only one of those tools.

> Why young engineers hate / disdain writing @U052TCFJH this is ironic in my personal trajectory: I started out in my youth enjoying writing, if often ineffectively and obliviously. it was only after validating the long-cycle effects of my writing that I learned to try to be more effective, which became harder, and increasingly disdainful as an exercise—none of those three problems became my problems, but rather, as the R.E.M. line goes, "I've said too much, I haven't said enough" (editing and scoping). meanwhile, I know plenty of young engineers today who are in their own place with both writing well and liking it.

“writing as a tool for thinking” is not, in my view, remotely the same thing as “architecture astronauts dreaming castles in the air, wholly unsupported by working examples, software artifacts, or empirical evidence.” I guess it was an unstated assumption on my part that “evidence” is an integral part of “good writing.” so I doubt we actually disagree on the point that writing has to be buttressed by other practices; we are, after all, all programmers here, and our job is not primarily to produce the written word.

@UMY8HG1HR > so correlated along the spectrum of writerly effect is writerly waste, the survivor effect scales down in correlation too. I agree. Though I believe that is a feature of the process, not a bug, because knowledge production is inherently "wasteful". Creativity even more so. The vast majority of commit messages are never re-read. Most design docs gather dust. Code comments go stale, or get deleted. This property of material is no different from code... most code is wasted in the same sense.

@U06GLTD17 re: https://clojurians.slack.com/archives/C03RZGPG3/p1712451861957139?thread_ts=1712375583.444789&cid=C03RZGPG3. I think simple, common-sense "developerly" writing is good practice in general, but there is no one-size-fits-all formula. Some place may thrive for some time just by writing good enough commit messages. As and when things they do get more complex, they'll have to find better ways of dealing with that complexity. By and by, the value of a shared writing practice pays for itself many times over (smaller team size, faster time-to-fix, consistently good time-to-market, ability to make large changes safely). Plus, there is no substitute to shipping well-tested working code. The benefits of writing culture only accrue if the software / systems are not on fire all the time. Architecture astronautics is pathological too. If all one has are paper designs, all one can do is fly paper planes 😅

I don't disdain writing -- I know it's important -- but I'm very, very slow at writing anything long form and my experiences suggest most of my colleagues over the decades tend not to read anything long form anyway.@U04V70XH6 I feel the same way about my code... takes me forever to write anything, and then most of my colleagues don't read it. Jokes apart (though I really am a slow programmer), I think writing and reading friction is very real. All writing has a lifetime, most of it is useful in-process. As a thumb rule, whatever is useful to more than one person on a regular basis tends to get maintained. Providing structure makes it easier for everyone concerned (writing guide (e.g. use headlines and bullet points), starter templates for different writing formats, examples etc.). Also some lightweight but active coaching and mentoring, because nobody will do it if they never tried a thing and experienced its utility. I think this sort of staff development is a marker of constructive engineering management.

I agree. Though I believe that is a feature of the process, not a bug, because knowledge production is inherently "wasteful". … most code is wasted in the same sense.it's not a bug, it can be cause for disdain, that's all. I ultimately agree with your conclusion to appreciate more and better writing, but wanted to qualify the premises. fundamentally I think I favor a weaker, less universal version of the argument. writing better and more of the time would be a good idea for some people working on some kinds of software problems to gain leverage, sometimes socially, sometimes individually, but it might not be the best path to leverage for everyone at all times, it does not work deterministically, and enhancing leverage may not even be needed all the time. I think the root of the difference is in the imperfection of the analogy, "We are software authors. Writing is what we do." (I take it as an analogy because if writing is literally already what we do, then there can't be a problem of not enough writing.) other analogies resonate: in some contexts, some of us are not so much software authors as software gardeners, plumbers, carpenters, builders, bricklayers, surgeons, nurses, mechanics, cleaners, etc. in other words, the useful and normative documentary thresholds can vary. the consequence of this position is I'm perhaps less inclined to expect a random engineer to partake by default, and might work with their other strengths instead, and only offer targeted advice about writing if I find it might suit them or the brief.

I love all the nuances you've been bringing out... Thank you . In practice, I am (or at least, I believe I am) not a hardcore "do this or else" practitioner. The thinking leans idealist (for what is life without dreams, eh?), the doing is very much pragmatic. There are no silver bullets and no magic salves.

Practically, my success criterion is "A 10% notional 'gain of leverage' of one busy person in a team of 10 can act as a force-multiplier". I think of it like concurrency problems. Marginal pressure reduction off a contended main thread can remarkably improve throughput of a whole system.

For communicating technical or computational ideas, prose falls short. The prose needs to be simple but heavily augmented with illustrative code, preferably interpreted dynamically too - notebook style. Confusing the communication of computational ideas with writing prose is the reason why tech documentation is ineffective. The idea needs simple prose, but the soul is really how you illustrate code and get a sense of how and why the idea works.

I agree with the premise of augmenting, but I think in terms of "yes-and"... progressive augmentation, if needed. Useful prose is useful. Useful prose with illustrative live code could be more useful. Maybe pseudo code is good enough, and maybe it is better because it does not suggest a specific code implementation. Or it ought to be a concept note with a live demo. Or it just needs a good ol' table and maybe a diagram. Sometimes, a talk is best to get things across in more dimensions (preferably with a transcript). Exemplary code has its place for sure and I use it often. Yet, typically, the way something is, or ought to be is the object of thought, and there are many ways to illustrate that.

Apropos live notebooks, I recently saw a codebase that uses Clerk to lens into various parts of the actual source itself. Pretty neat... I didn't know one could do that! I tend to use org-mode documents, with org-babel's polyglot goodness. Even if the babel stuff is not accessible outside of Emacs, I can commit the whole plaintext file to source, with results capture. This ensures even a static file is a legible (and hopefully good) illustration.

Generally, it's great to have some way to slurp actual source into a live notebook. https://gitlab.com/nilenso/cats/-/commit/40c67ef33ba1fec39c7ca81fb836f1dcc222a8fd from one of my study projects. I started an org file to interactively run curl tests, while I was figuring out the shape of the app's api. Then I wanted to run the tests in CI, and have them available to anyone else for local dev. I set it up so that code sat in a shell script for CI / local use, that a corresponding org file could slurp in at will ("detangle"), for interactive use.

Clerk has some illustrations from sussman's sicm in clojure. Its a great example of how to express super complicated and abstract ideas. - https://github.com/nextjournal/clerk-demo/blob/main/notebooks/sicmutils.clj

I've thought before (probably naively) that deps.edn but for OS package management would be amazing.

With an epochal time model on top to handle state transition

This is fun 😄

Seeing all of the pieces work together is amazing

And by pieces I mean other people's machines

Lots of memories of the original game flooding back. Thanks for the link