Hacker News Reader

> Why is it hard?

It is an incredible mental balancing act when you think about it. Your goal is to get some information into someone's head. To do that, you need to actually simulate their brain using yours. You have to think about how that person learns, what they already know, and how to incrementally build up your information in a way that makes sense to them. You have to think about what words and idioms they're familiar with, whether they learn top-down or bottom-up, etc.

In order to get into their mindset, you have to temporarily pretend to not know the thing you are explaining. At the same time, you are explaining it, so you have to simultaneously hold that very same thing in the forefront of your mind.

Now consider that each potential reader learns differently and knows different things so when imagining your audience, you have to do the whole process above in parallel for a number of different imagined audiences.

Doing this well requires a lot of theory of mind skill, and that's something that I think a lot of technical people are not very good at. My experience is that a lot of people who are drawn to tech are that way because they've found it easier to get along with machines because machines "make sense" and are simpler, which to me points to less theory of mind ability.

> Doing this well requires a lot of theory of mind skill, and that's something that I think a lot of technical people are not very good at

So very true.

"Theory of mind" is a good term. "Empathy" is another.

It is a good term:

https://en.wikipedia.org/wiki/Theory_of_mind

My wife and daughter are on the spectrum and it has been an interesting (and often difficult) experience to spend a lot of time around people whose intuitive theory of mind isn't as strong as a typical person's.

It made me realize how much we take for granted the dedicated brain regions we have for social cognition. For most of us, it's completely effortless to know "Oh, I told her ___ so she'll want ___." We do that processing as automatically as we recognize faces or climb stairs with a cup of coffee in our hands.

But for people on the spectrum, it's like the wetware is reduced, like having bad balance or no sense of direction. They can do the same task deliberately by focusing all of their attention on it, using the general-purpose calculator part of their brain to do a job most of us rely on dedicated hardware for.

Doing that takes a lot out of them. Imagine if every conversation felt like a calculus test. When they don't do that, it manifests itself in all sorts of behaviorally strange ways. There's the classic stuff like unusual affect and eye contact. But the one I notice a lot now that I'm attuned to it is pronouns. They will often use a pronoun to refer to a noun they've never introduced, because they are already thinking of that noun and didn't notice that they never mentioned it explicitly.

Brains are weird.

great point. i don't generally buy the argument that coding is drastically different from writing, insofar as it's laying out symbols in a way that can be understood (and followed) by another actor. that's a technical skill that's fairly transferable between the two.

but it is drastically different in how it's interpreted by that other actor: computers are (designed to be) fairly rigid in interpretation (the frontier of that not being so is fascinating but in its infancy), so that there's little-to-no variance in the output. people are completely flexible in comparison. inputs can generate a wide range of outputs, and there's little control over that range within the writing itself. that seems to frustrate many coders.

even the purpose can vary. coding is generally imperative in nature: do what i tell you to do. writing is generally persuasive (here's what i think, why i think it, and why you should think it too), since it's hard to force the imperative.

writing is necessarily harder than coding, because the target has so much greater complexity.

> i don't generally buy the argument that coding is drastically different from writing, insofar as it's laying out symbols in a way that can be understood (and followed) by another actor. that's a technical skill that's fairly transferable between the two

That's a great observation. A bit of a tangent, but I enjoy writing code with a tight feedback loop. Either with a debugger, a set of unit tests.

With writing, the feedback loop is not there. It's not clear whether the message achieves the desired effect.

Framing writing this way, explains why it's such a challenging activity. At least in my mind.

yes, another good point. you have to be your own feedback loop, simulating as many other minds in your head as you can, as @munificent laid out. it seems that proofreaders and editors came about to help in that regard.

If you write code intending it to have good human readability - and you really should - you have the same problem writing code.

I spend a lot of time rereading my code imagining I'm someone else who's never seen it before. Not sure everyone does.

> but it is drastically different in how it's interpreted by that other actor: computers are (designed to be) fairly rigid in interpretation (the frontier of that not being so is fascinating but in its infancy), so that there's little-to-no variance in the output.

Yes, I like to tell people that English is a programming language with no official spec and a billion partially incompatible compilers.

Yep. I’ve been on a few remote teams where I write a lot (in plain language too), and have found that if my audience is non-technical management that they simply don’t read it. Decisions continue to be made on their gut whims despite access to the critical information.

I guess that what the article is on about. Writing on its own isn’t enough, the culture must be set top-down to include reading and value added communications as well.

I think a lot of workers who do not have a craft per se just want to coast and pretend to work, and get offended or embarrassed when they encounter serious contributors that make them look useless.

There is an attitude toward the writer of “if you know the topic so well, then just handle ‘it’ and get ‘it’ done”. Unfortunately their idea of “it” has nothing in common with what is described or advocated in the writings.

> I’ve been on a few remote teams where I write a lot (in plain language too), and have found that if my audience is non-technical management that they simply don’t read it. Decisions continue to be made on their gut whims despite access to the critical information.

It feels like writing in a business context can easily enter TLDR territory.

I've often felt like I've had to write walls of text regarding various things, where it feels like there has to be a better more efficient way to transfer information between parties.

Walls of text work well for technical documentation, not so much with other things. You want to be concise, but often you literally cannot be.

Maybe a tool like Loom can be useful, but personally I hate watching a video when I can read instead. Maybe others disagree.

that's easily solved by a summary at the beginning of the document, laying out the premise, the conlusions, and a short thread connecting the two.

if you want to get fancy, you can work on organizing the document itself so that it's easily scanned for pertienent info (headings, charts, graphs, footnotes, etc.). but as the oft-quoted twain is said to have said: "I didn’t have time to write you a short letter, so I wrote you a long one."

> It feels like writing in a business context can easily enter TLDR territory.

I frequently actually put "TLDR: Whatever-the-point-is" at the top of my presentations/write ups, and then use the paper to actually provide support and pro/cons.

Absolutely this. I've actually seen company founders get frustrated and upset at waking up and having Slack channels filled with complex debate that happened over night (even when they didn't need to read it). Not for any clearly articulated reason, just a vague feeling that people shouldn't do that.

Eventually it came out that a big part of it was:

1. Slow reading skills

2. Slow typing skills

With the result that some people felt they just couldn't keep up in such debates and would thus effectively lose by default. This was frustrating to the group of us that could read, write and type quickly because it was basically a mostly implied request that we stop being good at our jobs. The thing you say about workers "without a craft per se" just rings so true to me.

Most writing is written for the purpose of being filed, not read. It's as simple as that - it takes exponentially more work to write something that you intend and want people to read. Most engineers just cannot be bothered with such a menial "soft" skill - the information should be interesting enough, right?

Well, no. I kind of thought my creative writing classes were a stupid joke at the time, but 15 years after graduating college, it is very clear that storytelling is one of the most effective persuasion techniques I've learned or seen. It's an incredibly effective way of transmitting information - if you can frame your outage post-mortem like a story with a central conflict, rising action, a climax and a resolution, you'll find that it just seems to be repeated and transmitted by itself. Very few people, even engineers want to read a boring timeline that dryly lists what happened in sequential order. Lots of people want to read an adventure starring an engineer who bumbled into a huge conflict and had to fix it before the business imploded.

If you find yourself writing things that no one is reading, try making it more read more like a story. we've all known someone who could take some mundane thing like going on a date and make it interesting with a few storytelling techniques. We might even have a few stories ourselves that we've been crafting over the years. Think about the techniques you use to tell interesting stories - misdirection, suspense, shared context and start applying them to your documents.

Edit: To clarify: Please don't take the advice that structuring your documents to be more like a story means write one of those posts we all groan about constantly that takes a two paragraph report and turns it into a multipage short story. For God's sake don't start your post mortem doc like: "It was a sunny day in March. Birds were chirping. The air was light and airy. As I poured my coffee into my favorite mug that expressed my personality in porcelain, I knew something was amiss. Today was going to be different." Just consider structuring your documents to be more readable and flowing.

> Writing is hard. Why is it hard? And how can people learn to write better? Those would be worthy topics for a longer post, which are not addressed in this one.

Amazon has a half-day internal course on business writing because it's taken so seriously. Everyone on the corporate side is encouraged to take it. This results in better writing, on average, which lets everyone see the value of good writing.

It's an investment that pays off.

Do they have any materials available to the public? I vaguely remember reading about their approach to meetings (written agenda with context which everyone must read prior etc. )

> Writing is hard. Why is it hard?

Usually because the underlying ideas are inchoate, so bad writing is often a good diagnostic for muddy thinking.

How often do you use the word inchoate when speaking?

I think writing is hard for those who's effect can be summed up as individual contributor. The moment you have to work in teams with a head count greater than 1m writing and effective communication become important. It's just people don't really lean into it like programming. They payoff has a slower feedback mechanism.

Every couple of months or so, I guess.

Besides the fact that most people are not all that great at writing, it is also often not to their advantage to write at all. At worst, they are in an organisation that will offshore their job at the earliest moment it seems they are easily replaced. In the more benign and common case, writing a lot is not directly detrimental to their career but it will not be that advantageous either. Written documentation is by nature usually technical in nature and therefore not often read or noticed by management. It does however take a lot of time to write, time which can not be spent on the parts of your job that get measured with KPIs or OKRs or whatever. This means that spending a lot of time on good documentation will make you "less productive" according to the measurements you are graded on for career advancement. I wonder how that would fare if you have a separate "documentation secretary", since helping those understand the code you just wrote has the same drawbacks as working on the documentation yourself.

I imagine one could be part-tester and part-writer. Both the tester and the documentation writer need to understand how the application works (at least from user perspective). The work for testers comes in waves; they could work on documentation between the waves. It could even make sense to highlight in user documentation, which parts are already done and tested, and which are still missing.

But these days many companies don't even have testers as a separate position, so... dunno, who else is left, besides managers and developers? Perhaps the janitors could take some extra reponsibility.

> I wonder how that would fare if you have a separate "documentation secretary", since helping those understand the code you just wrote has the same drawbacks as working on the documentation yourself.

Google has tech writers. Works well.

This is a great point. The issue is that the current best practice advice is to use a wiki.

Wikis are riddled with problems. They become out of date quickly. They need a librarian over time to organize the content in a way that's meaningful. There's also no "habit loop" to encourage people to regularly contribute content.

Right now, wikis are a tax on the most productive people in a company. If someone asks you the same question over and over, you will eventually document it to share.

At my company (https://www.friday.app/) we've found a way to get people to regularly communicate asynchronously via regular updates like daily standups or weekly status reports. It's more like a work journal vs. a file cabinet.

You don't have to be Stephen King to write clear technical documentation for your fellow teammates.

I think that people can learn some writing with practice (I know because I did). But it's like with everything, if you don't practice, you will never learn. IMHO, this just stresses the importance of having culture where things are written down.

I suggest as a starting point, just write as if you were explaining the subject or code to somebody. Use full sentences, not bullet points.

I think it's also important to have a culture of reading, not just writing. Otherewise, nobody will ever know if the writing is any good. It's like with backups - you don't actually have one until you've successfully restored your system from it.

Onboarding is a good moment for testing a lot of internal documentation. Instead of getting a senior to help set up a new hire, give the newcomer a list of Wiki pages and see if they can set themselves up from it. If they struggle, you'll know what exactly needs fixing.

>> I think it's also important to have a culture of reading, not just writing.

That's certainly part of the key at Amazon. Documents are written to be _read_ and _used_ in critical decision-making.

If you regularly don't read the documents distributed at the beginning of meetings and then ask questions that are clearly answered in those documents, you will be "profoundly unsuccessful" at Amazon.

(How's that for a euphemism?)

> I do not believe that many people will ever learn to write well; I also don't think it's worthwhile to make them try.

If you're someone who aspires to write well some day, I think it's worth drawing a further distinction. /u/blueyes might agree with this:

"I do not believe that many people will ever learn to write well, unless this person believes learning to write well is worth the effort. If someone doesn't want to learn to write well, it's not worthwhile to make them try."

Which means that if _you_, reader, want to write better, it's worth trying to do so.

If you don't want to write better, well, you've not read this far, so don't worry about it.

edit: grammar x2 It's not easy to write clearly.

>If someone doesn't want to learn to write well, it's not worthwhile to make them try.

And they have to be committed to putting the effort/time into it. Courses are fine--especially for communicating your organization's style and guidelines. But, for the most part, good writers write a lot. (Working with a good editor can help too.)

If someone sees writing as a real chore they're probably not going to get very good at it any more than someone who loathes the sight of a given musical instrument is likely going to become an expert musician.

There’s a distinction between learning to write well at length or often — and learning to write well enough for clear, concise communication. The former is not something everyone needs or values. The latter is one everyone should work on, especially now that we are all communicating via chat, email, comments, social posts, and other written methods. Effectively communicating your thought or opinion is a skill worth honing.

It’s hard because the beneficiaries of writing are different than the writers. It’s only in very strong cultures where execs put a premium on this on measuring talent. “Not only finish your work, and these three other tasks, but write about it too.”

Organizations can pull it off if enough people do it long enough, and they make heroes of the great writers. You see it in companies that are best in class in talent management.

Writing is half the issue. Most people are not very good readers, even of well-written material.

I work with a lot of people who didn't take the college track to become what they are today. I'm not saying that college is necessary or that one way is better or worse than the other, but the one thing I notice most about them is that they do not communicate through writing well.

The single most important thing, in my opinion, that these folks are missing is they do not write with an audience in mind.

Our manager's boss doesn't need long technical emails.

"javascript|ruby|python developers" should not need documentation on how "javascript|ruby|python" themselves or their standard libraries work. There is documentation for that already, but I have been asked to document such things.

We can't have writing that effects clear communication, because nearly everyone is too busy, or too important, or has decided that pretending to be too busy is a way of increasing one's perceived importance, or all of the aforementioned. So they dash off sentence fragments, peppered with inflated vocabulary and buzzwords, and punctuated with ellipses, comma faults, and worse.

When the above isn't the case, then you have the people who are too lazy: they cannot be bothered to simply read over to themselves what they've written even one time. And when they aren't merely lazy, then they're simply too dull-witted to understand the need for this.

Lastly, you have the people -- perhaps overrepresented in tech -- who suffer from something like an underdeveloped theory of mind. On some fundamental level, they don't understand that what is in their mind is not necessarily in the mind of the reader; and so they lack Clue Number One as to how to establish context.

Writing isn't difficult. People are difficult.

I think that organizations, in order share information well internally, should make certain people "writers" who get extract information from their colleagues and convey it to the team. They would be like the secretary in a meeting, but more ubiquitous. This would be part of their job description and KPIs and compensation.

I've seen organizations I think would benefit from this kind of role (both in the technical sector, and outside it). Unfortunately, it's been void for a long time-- and one that's not able to be "enabled" by some new technology (meaning that organizations could have been doing it already if they saw value in it). I think the long-standing fact that it remains a void probably means it's an idea that won't ever gain traction.

I'd love to see some case studies or hear anecdotes about businesses that either had-but-eliminated such roles, or businesses that developed such roles.

I've worked in organizations where talented people handle this work adjunct to their "real job". I've been amazed and delighted to be able to refer to documentation in those organizations where it existed. I've also seen those people leave and witnessed the product of their work lay fallow and "rot".

I've seen some documentation come out of more scientific-oriented technical industries (think 'Theory of Operation' texts accompanying old lab instruments) that are just wonderful. I get a real sense of "we have our stuff together" when I see that kind of documentation in a Customer-facing situation, and it gives me a (potentially false, of course) sense that the manufacturer really knows what they're doing if they can bother to produce documentation like that in a Customer-facing scenario. ("Imagine how good their internal documentation must be?") Then again, I'm apparently an odd duck because I get a lot of satisfaction out of creating and using good documentation.

> I've seen some documentation come out of more scientific-oriented technical industries (think 'Theory of Operation' texts accompanying old lab instruments) that are just wonderful.

I often use documentation as a gauge for how engaged a company is in making sure their product works in a way that makes sense. I've dropped part manufacturers before because they handed me documentation during evaluation that doesn't make any sense. Like the words are all on the page and someone obviously spent time writing the documentation but they don't make sense, like nobody actually read it.

My bottom line there is that I'm not going to waste my time emailing you every time I need to solve a new problem with your product. I pride myself on being able to respond to questions about how our product works and I refuse to become the middleman between our end customer and your sales engineer.

The first product I dropped for this was a thermal printer. After reading the documentation 3 times front to back I could not figure out what command to send the thing to make it issue a printout. I had to email the manufacturer for an explanation of the most important thing a printer can do.

Why is it so hard? Few are native speakers or passing for it. Few native speakers took their writing classes seriously, or at all. Almost no one reads for pleasure.

Interesting take.

Incidentally, the past 30 years have precisely seen the disappearance, but in very select types of businesses, of secretary/assistant/aide roles.

> Writing is hard. Why is it hard ?

Because not everyone thinks that way things are written. Depending on the person, translating ideas from the 'brain medium' to script can be really difficult.

I love giving presentations with white boards, using visual structures like graphs. I think if companies becomes more flexible about allowing teams to document things in a format that best suits their 'brain medium' then I think a lot more people would be willing to 'write more'. I

I'm often surprised by how bad people are able to handle basic computer stuff. For example: why TF don't you learn yourself how to type on a keyboard properly to accelerate your typing by like 10 times. Why TF are you not using the shortcuts your software is giving you to accelerate like 10 times.

I don't worry too much about it. In fact it kinda makes me happy. It just means your job is now safer, since you DO know all those shortcuts. ^^

It also results in newer iterations of products and software losing support for shortcuts and accelerators, because no one values or knows about them anymore, until every interface becomes dumbed down and considers touch as the primary and only possible way of interaction.