Write for One Person
wizardzines.com111 points by evakhoury 2 days ago
111 points by evakhoury 2 days ago
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.
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.
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'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.
For one company, I made documentation for archive and backup software and I worked closely with tech support. Most customers were sysadmins, and a small subset had no clue what they were doing and they would call us for every little thing even remotely connected to our software. One was a case of an image in a spam email wasn't able to be archived and they were freaking out about the error.
I also worked at a university and that was concerning because some students would just give up whenever anything didn't go right the first time. No troubleshooting skills at all. We were moving from Google to MS and they needed to use Takeout to backup their stuff locally, just in case something happened. But we got a lot of calls because it wasn't ready to download immediately. I've heard it's gotten worse.
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.
> 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.
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.
I don't know. Maybe you'll feel differently if you read my article. It's about conservative garbage collection, but I mythologized it as a story about people escaping the clutches of an orwellian surveillance machine created by technological wizards, until they learn the magical incantations required to find them.
Let's just say I definitely toned it down a bit in my next article.
I just read your article, and please don’t listen to the machines!!! It’s a very fun read, and I for one love some personality in an otherwise dry topic.
The thing about keeping your personality in your writing is that you will have to be prepared for it to rub some people the wrong way, even while some people (like me) like it much better: the only writing that no one dislikes is writing that no one likes, either.
Anyway, fight the corporate blandness, have fun in your writing, and keep it out there! That at least is my opinion.
PS if you add RSS I would gladly add your blog to my feed, based on this article.
That means a lot, thanks.
I do have RSS and Atom.
https://www.matheusmoreira.com/rss.xml
https://www.matheusmoreira.com/atom.xml
Please let me know if it doesn't work, I'll fix it.
Thanks for the links, added! The bit at the end with the assembly put me in mind of another favorite post, aphyr’s hexing the tech interview: https://aphyr.com/posts/341-hexing-the-technical-interview
This is an amazing article, thank you so much for posting this!!
(def racer
(->> [0xca 0xfe 0xba 0xbe
> “Magic numbers.” You are, after all, a witch. “Every class begins with a babe, in a cafe.”
> “What?”
I love it.
I feel like LLMs kind of speak to making things be average. For half the population that is a step up, but for the other half that is a step down.
It's right that they steer toward the center of their distribution. But I would offer a different view on whether that's a step up for half the population.
Writing isn't a distribution on a single dimension that goes from "bad" to "good". It's a lot of dimensions that encompass everything from "funny" to "formal", "precise" or "hysterical". They may be filled with metaphors, or use allegory; they may use math or logic to explain. The allegories could be from science fiction or they could be Biblical or 19th century Victorian novels. None of these are right or wrong, but they are opinionated ways to express an idea.
Writing feels better when it has real texture and character to it. That character is not the monodistribution of "bad" to "good". It's whether it inhabits pockets of out-of-distribution thought in the thousands of dimensions of "thought-space."
An LLM pushing to the center of distribution means it pushes the writing out of inhabiting any of the interesting pockets that create the feeling of texture. The middle of the distribution does not mean it is average quality: it means it's not good at all. The median of the distribution can be far worse than the median writer if you accept that the median writer has out-of-distribution thoughts on at least something, and that it is this which makes their thoughts interesting.
That's why a rough, perhaps not-totally-grammatical article written by someone with interesting thoughts is vastly better than a "correct" LLM revision, even if the human writer isn't a 'good' writer. Their article occupies an opinionated stance on some dimension that matters; it sits in a pocket of interestingness that LLMs seem almost totally unable to inhabit.
The exact middle of the distribution across thousands of dimensions may actually be one of the very worst places of them all.
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.
Negativity normally doesn't faze me. It's the insinuations of mental illness that hit me pretty hard. I quit the GNU bash mailing list after someone called my idea "schizophrenic", then like a year later I found out bash actually implemented a version of my library system idea.
Very often I think I'm insane because of the things I think. If it was so easy, much smarter people would have done it already. Then I write the program and it actually works.
> HN posters tend to be overly critical, often tripping over themselves to demonstrate
That's the helpful part though, as one of the only communities that is overly critical instead of too much on the other end of the spectrum like every other community. Criticism helps you refine and sometimes even see new perspectives, and the other chaff and useless comments you can just ignore, doesn't really matter, as your experience shows as well. Ultimately I think you get back what you put into the HN-machine.
I do agree LLMs water down human writings to a extreme degree and people should just wholesale avoid them except for very surface-level copy-editing fixes, like spelling mistakes. Don't ask for their feedback how something feels or if it's "dumb" or whatever, use your own intuition.
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!
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
Haha this is excellent, I believe you’ve just invented a new genre - Garbage Collector fanfiction.
I have no idea how reading this people would jump to the conclusion that you have problems, but I will jump to the conclusion that those people probably like to live in a gray box with blank walls
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
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.)
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 VonnegutYeah, 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.
a.k.a the vaunted "Ideal Customer Profile". This is really critical for many many things in business and life.
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.
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.
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!
Writing for "you, but three years ago" is excellent advice.
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.
wizardzines.com is one of the few things I am subscribed to by email <3