back
81 comments
I've spoken before a thousand several times saying with a straight face "Every audience is an audience of one."

My first example, I was asked to give one more talk on how one needs to shuffle seven times. There were four people, and a blackboard smaller than my kitchen window. I went for it like I was in office hours, which I've always enjoyed more than teaching. A few weeks later a phone call "I liked your talk." "Thank you." "Could you come to Switzerland to give it again? We can only offer a week's full expenses..."

Then I was asked to write a review of the off-broadway play "Proof" for the American Mathematical Society Notices. I didn't read it much, but I was told people do. I worked a very hard week on my review; my Swarthmore College classmate Ben Brantley's Broadway reviews were life or death for productions at the time, and I didn't want to embarrass myself. Ron Howard read my review, went to see "Proof" twice and loved it, and hired me to be the math consultant for "A Beautiful Mind". That was a transformative experience.

Every audience is indeed an audience of one.

https://www.ams.org/notices/200009/rev-bayer.pdf

To imagine a big audience as just 1 person sounds cool, but when I imagine the talks I need to give to a bigger audience, I find it very daunting. I can only hope that I overcome it soon.
Is there a link to the "shuffle seven times" talk?
That is truly awesome. Good on you.
Great story. Thank you.
> Often this person is me

I wrote an article that never fails to put a smile on my face every time I read it. I felt like I had finally found my own voice. Ran it through Claude and it told me to tone it down a bit, but I ignored the advice and published it anyway.

The article caused people on HN to say I had issues. They weren't exactly wrong, but still. Be careful with what you publish out there. Warm reception is never guaranteed. My one consolation is the fact Bob Nystrom apparently liked it.

One time a project I made appeared at the very top of the front page. It attracted many negative comments. Some saying it was barely usable. Others saying I'd built it wrong, and offering half-baked advice on how I should have done it instead. That project later went on to get me lots of work and recognition, and even won me a few industry awards.

HN posters tend to be overly critical, often tripping over themselves to demonstrate how they're smarter than the creator of whatever it is they're commenting on. In my experience, they rarely are.

I can't stand it when LLMs tell you to tone it down. Their writing advice is almost universally awful. They want you to write the most cliched bland content possible.

Sometimes I see technical people who feel they aren't good writers, but who have good ideas. They then turn to LLMs, believing that the LLM will help them express their good ideas. They're often right that they have good ideas. But the LLM just turns them to sawdust.

Kudos to spurning the mediocrity conversion machine and hitting publish.

> article caused people on HN to say I had issues.

Pretty much every time people use such arguments to put someone down it's just because they're insecure.

Also, who doesn't have issues? Literally everyone has.

Would you be willing to share it again here?

I love reading these personal things - especially the things that people publish in spite of being told they're crazy. In my experience they're usually the more real, honest and raw things in a crazy world where everyone is keeping up appearances and pretending to be normal and sane

Went looking for that article out of curiosity. For what it's worth, I think the original commenter expressed a fair opinion politely, but the "author has issues" commenter was unnecessarily unpleasant. Neither of those should prevent you from writing how you want!
I think one needs test audiences before they publish to the masses. We need the ability to play with our voice a bit to see how it connects well to the world
<3
I never try to speak to everyone as a tech writer. Tutorials are for people who'd never used our software before, but even then I could assume a certain level of computer literacy, for example they can launch out software or browse to a URL.

I can make How-to's that can assume they had gone through at least one of the tutorials, but even then I put links to the appropriate tutorials so they could refresh or learn if they needed it.

But lately it seems like people are getting more computer illiterate. So how low do you go? I am getting tempted to add a link to some basic computer literacy.

It's kinda like people complaining about Space Launch System, why aren't we using Saturn V or an improved version of it. We have the blueprints and schematics and everything but it appears there's a gap between what's written down there and what's in the textbooks. A lot of in-between experience has evaporated because shop classes and manufacturing were shut down.

I am realizing that a lot of experience was never written down and turned into institutional knowledge that could be used later. The AI companies would love this but it's gone because it was more cost-effective not to.

I've noticed people's "computer literacy" varies dramatically based on the applicability of whatever they're trying to accomplish to their personal desires versus work.

Being a bit hyperbolic: An update moves one pixel out of place in a line-of-business application and helldesk calls roll in from core-dumping end users who simply can't fathom how to use the software anymore. OTOH, big streaming video or shopping service revamps their UI and the end users seem to have no trouble continuing to use company resources to play videos, shop, etc.

Edit: I have no doubt many large websites have better UX resources, as compared to LoB apps, but user motivation plays a big part.

People are "getting more computer illiterate" because younger people were never taught computer literacy in the first place. We're past the point where children just automatically learn that by using computers, because computers are too reliable to require acquisition of those skills.

Compare to cars. Once upon a time, every car owner had to know how to maintain a car. Nowadays, you can get along perfectly fine having no idea what's going on under the hood.

> It's kinda like people complaining about Space Launch System, why aren't we using Saturn V or an improved version of it. We have the blueprints and schematics and everything but it appears there's a gap between what's written down there and what's in the textbooks. A lot of in-between experience has evaporated because shop classes and manufacturing were shut down.

Because it was designed to be manufactured using 1960s components. A lot of the parts it used aren’t even made anymore more, because they’ve been replaced by newer components

The Space Shuttles were progressively upgraded over time to address this, e.g. the early 90s upgrade of their computers which replaced core memory with semiconductor memory. If we’d kept the Saturn V series alive, todays Saturn Vs would have had rather different innards from the ones that flew in the 60s/70s

But this is why “just reuse the Saturn V” design never made sense. You have to redesign so much of it to substitute for unavailable original parts, you might as well just redesign from scratch

I'd be curious for some more anecdotes and analysis of the "more computer illiterate" line. I've tended to be in pretty siloed environments the last 5 years or so, and haven't noticed it myself, but I've heard some pretty bad anecdotes from people who are in education.
Write to please just one person. If you open a window and make love to the world, so to speak, your story will get pneumonia

  - Kurt Vonnegut
This reminds me of some comments by C.S. Lewis (paraphrasing from memory) on three ways of writing for children, two good and one bad:

- Writing for a specific child (think telling a story to someone specific)

- Writing because you have something to say and a story is how you want to say it

- Writing generally what you think a group of people want (e.g. "children like food so I'm writing a story about food")

I think the essay is available online, he is much more eloquent than I

Julia is a fantastic writer herself. I've long followed her work, and always been impressed with how great she is at distilling information.
There used to be a thing for addressing user interfaces to fake users with a profile. One talk on this for airline seat back entertainment systems had target users "Cletus", some old guy who just wants to watch movies, "Tim", a kid who wants to play games, etc. The speaker goes on and on about simplifying the UI for Cletus. I asked "Why not just give him a channel selector knob." There was a bit of stuttering, and then the speaker admits that this thing has a payment gateway and you have to pay to watch movies. So there's a complicated credit card entry UI.

Oh.

I write mostly for myself. That's a trite I guess observation considering that I happen to write a lot of private notes. But I think writing for broadcasting is overrated.

Journaling or diarying is writing for myself, and often in a form that will never leave the disk inside the the computer. But I also want to write more complicated things than just what I thought about today, how I solved some problem, or a reminder for three months from now. Why? Because writing as a solitary pursuit is similarily rewarding like reading for pleasure. We can read without growing an audience. We can read without have any extrinsic motivation. We can just do it and leave it at that. But writing is a bit too much associated with communicating (small) and broadcasting (large).

I could probably write a book on the most idiosyncratic topics, something that not even my mother would like to skim the foreword of. Because imagine if that process would help me know myself? How valuable would that be? The writing artifact might be useless, even. But the process could be enriching.

I would never hope to read a book by someone I don't know and be able to absorb their wisdom, not even 10%. Some things cannot be transmitted like that. The printing press probably has not helped us know ourselves more than just, you know modestly more. Some things have to be worked on by you and you alone.

This also translates to more practical subjects than knowing yourself. But that's what I felt like spending the word count here on.

But in terms of public writing. I am currently working on an article-length piece for a niche "publishing". And I find that process to be rewarding.

Hypertext to the rescue! Here's the lede sentence:

> In [Structured Query Language (SQL)](https://example.com/sql/), you can solve Unusual Complicated Problem with Super Advanced Thing.

That said, one time I had in mind a reader archetype, for whom I added an appendix of one basic concept, which ideally they'd already know, but likely didn't.

<https://docs.racket-lang.org/roomba/index.html#%28part._.Ass...>

I could've linked the some mentions of "association list" to a chapter of some textbook they'd never seen before-- and maybe they would read it, and maybe they would come back.

But instead, I decided to give a quick overview, in terms of an example relevant to what I was documenting, and leave them with a code pattern they could use, to get on with programming a robot like they came to my document to do.

(Though I wish I'd put an accessible showing-off demo example near the beginning of the document. After the intro, it reads a little too much like the glorified inline API docs that it is.)

Writing for "you, but three years ago" is excellent advice.
Or "you, but three years from now" in some cases. Logging my random OS changes or what were at the time "one-time shell scripts" in my journal has proven invaluable in some cases.
"You, before you embarked on this project" is another good target.

Much of the technical documentation I've written was effectively how I got from prior-to-current-project-me to after-current-project me. And is often written for future-me-who's-forgotten-what-I-learned-in-the-process.

What TFA fails to address is the option of either specifically naming prequisite knowledge OR basic prerequisite references. The number of sysadmin / tech manuals which re-iterate, e.g., basic bash/shell/editor commands, networking concepts, etc., etc., rather than simply pointing at a good definitive guide is ... frankly embarrassing. I'd rather see one good continuously-updated reference than thousands of writers reimplementing poorly-written, outdated, and very one-sided references.

Totally! I like the bit about writing for a colleague, because this gives you a much more relatable concept I think.
While I think this is good advice, I do think one can make the given writing more accessible by adding small details, like expanding acronyms the first time you use them. Or providing a link to introductory reading for a given topic, or just explain yourself. I've found that sometimes I was being too terse when describing something, and it made it hard for everyone to understand, not just beginners. But it took my less-technically-inclined friends to point it out because they were unable to understand it at all, as opposed to those who could understand it a little.
I love reading articles that are written like this. Whenever I encounter a word/concept that I don't know, I can just look it up and myself decide how much in-depth I want to go to understand this topic before going back to the article. Whenever basic concepts are explained, I automatically get the feeling that someone very inexperienced wrote this, and that my time would be better spent reading other material.
I've always written my blog for myself. I keep it as a record of what I'm working on, I suppose, or what I'm interested in. I was mildly surprise to find I had 279 blog posts on https://tech.stonecharioteer.com. I only ever write for myself. Whenever I try to write for an audience, I am not satisfied.
I get stuck when I try to post on social and my brain fills up with all the random people I know that have commented or complimented a post. The problem is there are wildly different expectations of what I post. Is anyone else dealing with this?

Lately I've decided to write for ME. What do I want to write about? That has made it a lot easier to get unstuck. That and not looking at the views, likes, etc.

I work in growth now, and I definitely resonate with this. Producing content about Kubernetes operator architecture is always going to be hard.

But you have to decide whether you alienate the beginners by assuming people know what CRDs and memory errors are — or the advanced practitioners by explaining pods, clusters, and other jargon from scratch.

You can't make everyone happy.

What about the complete opposite? Has anyone successfully used literate programming, perhaps even emulating Euclid's Elements, where you provide all the definitions (the precise meaning of concepts), postulates (system assumptions), common concepts (logical rules), propositions (functions), and implementations? Capturing all the logic in a document.
One thing I've noticed is that information is often either too basic or too advanced. The hardest resources to find are the ones that bridge that gap. Writing for a specific person often produces exactly that kind of explanation, which is probably why these posts end up helping so many others as well.
When I was giving presentations to fairly large groups for a larger company, the feedback forms would often include both "way too basic" and "really great insights."
Seriously! Every music theory blog post and video is like this. They're going to explain something like modes or maybe altered dominant scales, and they start out explaining intervals. Seriously stop, not from the beginning again! That's not your audience.
And for that matter, /developing/ for one person, often yourself, is probably better than for everyone. I’ll see this with app developers when they’re trying to figure out what kind of app or game to make. Just make the thing you would use!
Yeah, this is similar to finding 10 customers who love your software rather than 1,000 who only kinda like it. And if you do, it's probably because you've found a use case that is urgent enough for one specific kind of user.
Or explaining the basics (primitive) to a beginner in terms of advanced (tertiary) features of another system. If there is a target reader in mind call the article/book x for y devs.
Ah, personas!

https://bufferbuffer.com/using-personas-in-technical-writing...

>In user experience (UX) design, personas are fictional characters representing the different types of users who might use a product or service. These personas are based on user research and are designed to help designers and other stakeholders understand the needs, goals, and behaviors of the different types of users.

wizardzines.com is one of the few things I am subscribed to by email <3
a.k.a the vaunted "Ideal Customer Profile". This is really critical for many many things in business and life.
one has to wonder who julia is writing for here.
I tried applying the same principle for building a product.

Then, I have a few products that have maybe 10 users.

Too niche is an issue.

It is really hard to tell with products though. Sometimes the core idea is right, but you haven't yet refined it to match what your audience wants (ie, sometimes you're building for one person that you're not marketing to). Also sometimes it takes a long time to win over your target audience, even if your product is "perfect". In short, sometimes you're doing things correctly, but just gave up too early.

Of course, it is also possible to stay with a bad idea forever. Personally I don't think it's possible to know which scenario you're in (good idea but gave up too early, vs bad idea) until you either succeed or die.

It's called "target audience" and it is a well established meta tag for any writing. Not a new principle or rule.
XKCD 1053