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.
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 am late 50s and I still find talks overwhelming.
What has worked though is
1. Recordings. Go into zoom, and give a talk with recording on. Listen to yourself, just once per recording but more if you can tolerate your voice :) It shows you your common failure points in black and white so that you can work on them.
2. Presenter notes. During my final talk, I have succeeded when speaking without notes, but to get there I need notes. I write my script as presenter notes (in Mac Keynote). Because of ADHD or whatever, as I am speaking, new ideas pop up. Every single time. In early rehearsals, I pause immediately, update the notes first and then go back and rehearse. After a dozen iterations, sometimes 30 iterations, the edits disappear, you learn to live with what you finalized already. Also once you narrate it 30 times, you have all kinds of memory maps sorted out in your brain, so even if you derail, you mind does have the information. I have seen some people have presenter notes in bullet forms, does not work for me. In the beginning I need my speech written out.
3. Rehearsals. The 30 rehearsals I mentioned. Figure out what you need. 5 or 50? You will know when you are ready. Once you have your magic number, stick to it. Maybe 25 becomes 20, but do not short change yourself by saying ... no I can wing it.
4. The morning of. I have tried 2 approaches. One is just open the deck and speak through the notes in your head. No recording. No zoom. No notes. Your mind should have it. OR not even deck. Just close your eyes, I am usually on a recliner (do not nod off) and run the narration in your head. Mistakes ... happen
5. Seating. Most of our presentations are in conference room settings but with remote viewers. Sometimes they are purely on video. Figure out the setup and rehearse 1-2 rounds in live mode. If you will be in a conference room, find one similar and rehearse once in that setting. If you will be seated and speaking to local + remote audience, try to visualize that as you present. It never feels the same with live audience, but it does give you some muscle memory.
6. Timing and Clickability. Transitions sometimes take more (or less clicks) than you envisioned. Practice them. If you are given 3 minutes, or 30, time yourself so that you know how far are you. Sometimes you need to be pitch perfect, but sometimes you can tolerate 10%. If I am at 10% variance, I stop fine tuning. As people ask questions, small variations can be tackled.
If someone else is sharing the screen and you are just speaking, rehearse that with them, because "next slide" handoff gets tiring very soon. To help them, add a line [ Click ] in the notes so that they know the click is coming when you get to a specific speech.
7. Screen setup. Over time, I am learning to speak from my mind (or heart). But the notes are there. I work on Mac Keynote, so there is a presentation mode where I can see what is on screen now, and what will be on screen next as soon as I click. The notes are there but they are only a last resort. If you are familiar with what is on screen, and what is coming next, you do not need to look at the conference room screen, OR any other window. These are usually enough to tell what you need. I make them the maximum size possible - do note that I have 2 screens side by side (current and next) so their sizes are still small on a laptop window, but having the biggest size I can get allows me to interpret fine variations - sometimes the next click makes only a small change, so having them visible helps.
8. Notifications off. Do not look at notifications. Ignore them. It is hard, but do it. 2 presentations back, one notification disrupted me so bad, I choked. I read the notification, it was at the beginning of session and someone just saying "sorry for joining late" and by the time I read it, my mind had disconnected. I started reading from the notes and never recovered from there. Maybe part of it was that I was not prepared - I did not have the 30 rehearsals. We did the work in 3 days, and 3 days was not enough for me to iterate on the slides, rehearse, have notes ... so when the chokepoint happened, my brain could not take it. But notifications is what triggered the disruption (of a bad kind).
This is incredible advice across the board. Would you consider writing this somewhere and submitting it as a post? I think this is valuable and worth repeating.
Great advice. One point I’d add is to just let yourself be nervous. Once I accept that my voice will wobble and my hands will shake then nervousness starts to feel a little more like excitement.
Rehearsal works great for fighting nervousness. Just the mere thought of speaking in front of 30+ people makes my heart slightly faster, but once I have a presentation down to the minute and can go through it 100% without looking at my notes, the nervousness dies down a lot and confidence starts taking over instead.
Of course, it reverses back the second you take a step into the stage, but it gets a whole lot worse when you don't remember what to say, and once you've spoken for 4-5 minutes the confidence seemingly remembers to come back by itself too.
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.
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.
I'm sorry to hear that. If it's any consolation, people often say I act like an alien pretending to be a human. Maybe it's just the price I pay for being an inquisitive person.
> 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.
I get where you're coming from, and I agree to some extent, but I do think our tendency to weight criticism more favorably than praise (as if praise is "chaff" and criticism is automatically valuable) can be dangerous. This negativity bias unfortunately led me to adopt less-than-optimal ways of working in my younger years, because I assumed the people offering me criticism knew what they were talking about, when this wasn't always the case.
So while criticism can be valuable, I think it's worth reflecting an equally critical eye back at the person who is offering it, as upon closer inspection they may not be worth listening to at all.
> because I assumed the people offering me criticism knew what they were talking about
I feel like this is the issue, and it's everywhere, not just HN. So 'fixing' HN wouldn't really solve the problem, each individual needs to learn what criticism they can listen to VS not. In the AFK world we have the benefit of knowing people, so you can implicitly trust some of them, but on the internet you need to first calibrate your "bullshit sensor" so you know what take aways you can actually take vs not.
> So while criticism can be valuable, I think it's worth reflecting an equally critical eye back at the person who is offering it, as upon closer inspection they may not be worth listening to at all.
Indeed, I agree :) As long as this happens based on what the person wrote rather than who the person is, you'll learn to eventually get really good at this, and all the mindless criticism becomes no-ops essentially :)
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 read this in the voice and cadence of a D&D dungeon master reciting an epic tale,
The dark mages often braved the underworld themselves and were therefore undaunted by the task. It should not be difficult, they thought, to adapt the machine to do it. Why couldn't it travel the foreign lands? There was no reason. And so it was decided. The machine would be taught how to do it.
The resources available at the garbage collector's disposal were substantial. It had the object census. It had a list of roots which it would search for objects. It would reap all objects it didn't find in those roots.
One of those roots is the lisp stack. As the program churns, values are placed in stasis and stored there so that they may be recovered later when needed. It is when they escape from this stack that they create havoc in dynamic society. But where are they escaping to?
It reminded me of this ad for a video game cosmetic. It had the same brought-a-smile-to-my-face energy. :)
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.
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.
There's this TV series, Doctor Who. Its two most recent seasons have been produced in partnership with Disney.
The latest Doctor's era started with a Christmas special. The episode is told from the perspective of Ruby, his soon-to-be assistant, who appears to be troubled by a suspiciously consistent streak of really bad luck in her life. The Doctor is first shown as a mysterious figure suddenly showing up out of nowhere to catch a glass that Ruby just dropped at a club before it reached the floor, just to disappear a moment later without any introduction. He makes an impression of some "fairy godmother"-style character that stays hidden in the background, pops up to help Ruby and disappears immediately afterwards. Some time afterwards Ruby gets into a really serious trouble and the Doctor finally steps in to triumphant music to save the day and starts fully interacting with Ruby. Pretty common and effective way to do a build up to an introduction of a mysterious character, you'd say.
Except... there's one extra scene with him placed in between. As a yet another instance of Ruby's mysterious bad luck, a huge promo installation depicting a snowman is about to fall from a building's elevation onto the taxi she's riding in. She's completely unaware of the danger, but of course, the Doctor is there in the background to save her again; he makes the traffic lights switch faster so the taxi is already gone before the snowman falls. However, that's not the end of the scene - it appears that the snowman will now fall onto some pedestrian who now entered the crossing, who appears to be a mother with a child in a baby stroller. The Doctor rushes to push her away, the snowman falls onto him instead, though it turns out to be empty inside so he isn't harmed after all and the stroller turns out to be filled with Christmas presents rather than a baby. A policeman shows up, questioning the Doctor for a bit about what just happened there. The Doctor introduces himself in a short conversation with the policeman before he goes away.
I was quite baffled while watching that scene and once I finished that episode I kept wondering what was it about. I couldn't see the point of it, it wasn't telling us anything new that we didn't already knew about Ruby, the policeman is nowhere to be seen again either, it only seemed to diminish the later scene when the Doctor finally gets into the action properly and steals the spotlight. You can't successfully build up to an exciting entrance when you just had another less remarkable entrance already. It also felt out of place as this one moment wasn't being told from the Ruby's perspective anymore - the taxi with her inside was already far away. He still introduces himself to Ruby later on, so you could just cut that scene entirely and no value would be lost. In fact, I'd say you would actually add some value this way, as it felt to me that the episode would simply flow better without that scene.
Fast forward some time and I stumble onto commentary track of one of the episodes. Here I hear the episode's writer (and showrunner) talking a bit about how the collaboration with Disney goes. He says that he has plenty of creative freedom and Disney is rather off-hands, but they do come back with some notes from early screening panel testing that he isn't required to act upon but which he considers useful regardless. As an example, he mentions that the Christmas special episode got some early feedback from Disney during production - it took quite some time for the episode to introduce the main character and the test audiences were getting impatient, wanting him to be introduced earlier. The writer then concluded that he decided this feedback makes perfect sense, so they did late shoots to include an additional introduction scene - the one I described above which existence baffled me while watching. This explained everything: the Doctor's triumphant entrance was clearly meant to be the moment of his big reveal, but now it just wasn't anymore, all because of applying seemingly reasonable feedback that was meant to make the episode better.
This is kinda what applying LLM feedback to your writing feels to me. You see some argument being made and it makes sense when you think about it, so you apply the proposed changes, forgetting about what made you write it the way you did it in the first place. In the end, the result gets worse for one reason or another. You "fix" things that were actually load bearing and allowed the reader to connect with your thoughts better.
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
I just skimmed it and dont see how anyone would come to a conclusion of schizophrenia/mental illness.
However, I only skimmed it because I REALLY did not care for all the prose etc... It was literally unreadable/incomprehensible (without investing considerably more effort). This seems to echo one of the comments in the original HN discussion.
But, if it made you happy to write and re-read it, then I'm in favour of it. Keep doing your thing. Evidently some other people like it as well.
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
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
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 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.
Streaming sites and shopping carts are used by millions of people, but casually after work, maybe twice a day.
LoBs are used intensively for hours on end in a busy work day, and most people's livelihoods depend on them either directly or indirectly. You grow into them. Muscle memory used to be an actual UI design goal, back when TUI's were the most common LoB interface. Not so much anymore when everything is web app and you click through the horrid UI slowly with your mouse pointer, and repeat this identical task 200 times in a day.
edit: We naturally develop a muscle memory even for the worst LoB. But they are not designed with this in mind. If they were, they wouldn't move that one critical pixel around in a mouse driven app.
> 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
> Because the SLS uses left over Space Shuttle engines. Once.
The reused RS-25s aren’t the same as the ones that flew on the STS-1. STS-1 used the original RS-25, Artemis uses RS-25D, and will in future use the new RS-25E.
In the same way, if Saturn V survived to the present, we wouldn’t be using the original F-1s/J-2s any more, we’d be a using significantly enhanced versions-and the originals would be infeasible to manufacture due to component availability changes
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.
But, but, they're digital natives, oh course they know all about computers. /s
I get that. I used to be able to overhaul a VW beetle on the side of the road with regular tools. A couple of years ago my car's transmission's computer went out on the interstate. I couldn't even get a useful error code. The shop down the street didn't have a high enough end device to talk to it. While the dealer was able to figure it out; it took nearly a month to get the replacement part. I'm car semi-literate.
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.
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.
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.
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.
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.)
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.
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.
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.
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.
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.
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.
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.
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!
>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.
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.
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.
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.
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.
I am late 50s and I still find talks overwhelming.
What has worked though is
1. Recordings. Go into zoom, and give a talk with recording on. Listen to yourself, just once per recording but more if you can tolerate your voice :) It shows you your common failure points in black and white so that you can work on them.
2. Presenter notes. During my final talk, I have succeeded when speaking without notes, but to get there I need notes. I write my script as presenter notes (in Mac Keynote). Because of ADHD or whatever, as I am speaking, new ideas pop up. Every single time. In early rehearsals, I pause immediately, update the notes first and then go back and rehearse. After a dozen iterations, sometimes 30 iterations, the edits disappear, you learn to live with what you finalized already. Also once you narrate it 30 times, you have all kinds of memory maps sorted out in your brain, so even if you derail, you mind does have the information. I have seen some people have presenter notes in bullet forms, does not work for me. In the beginning I need my speech written out.
3. Rehearsals. The 30 rehearsals I mentioned. Figure out what you need. 5 or 50? You will know when you are ready. Once you have your magic number, stick to it. Maybe 25 becomes 20, but do not short change yourself by saying ... no I can wing it.
4. The morning of. I have tried 2 approaches. One is just open the deck and speak through the notes in your head. No recording. No zoom. No notes. Your mind should have it. OR not even deck. Just close your eyes, I am usually on a recliner (do not nod off) and run the narration in your head. Mistakes ... happen
5. Seating. Most of our presentations are in conference room settings but with remote viewers. Sometimes they are purely on video. Figure out the setup and rehearse 1-2 rounds in live mode. If you will be in a conference room, find one similar and rehearse once in that setting. If you will be seated and speaking to local + remote audience, try to visualize that as you present. It never feels the same with live audience, but it does give you some muscle memory.
6. Timing and Clickability. Transitions sometimes take more (or less clicks) than you envisioned. Practice them. If you are given 3 minutes, or 30, time yourself so that you know how far are you. Sometimes you need to be pitch perfect, but sometimes you can tolerate 10%. If I am at 10% variance, I stop fine tuning. As people ask questions, small variations can be tackled.
If someone else is sharing the screen and you are just speaking, rehearse that with them, because "next slide" handoff gets tiring very soon. To help them, add a line [ Click ] in the notes so that they know the click is coming when you get to a specific speech.
7. Screen setup. Over time, I am learning to speak from my mind (or heart). But the notes are there. I work on Mac Keynote, so there is a presentation mode where I can see what is on screen now, and what will be on screen next as soon as I click. The notes are there but they are only a last resort. If you are familiar with what is on screen, and what is coming next, you do not need to look at the conference room screen, OR any other window. These are usually enough to tell what you need. I make them the maximum size possible - do note that I have 2 screens side by side (current and next) so their sizes are still small on a laptop window, but having the biggest size I can get allows me to interpret fine variations - sometimes the next click makes only a small change, so having them visible helps.
8. Notifications off. Do not look at notifications. Ignore them. It is hard, but do it. 2 presentations back, one notification disrupted me so bad, I choked. I read the notification, it was at the beginning of session and someone just saying "sorry for joining late" and by the time I read it, my mind had disconnected. I started reading from the notes and never recovered from there. Maybe part of it was that I was not prepared - I did not have the 30 rehearsals. We did the work in 3 days, and 3 days was not enough for me to iterate on the slides, rehearse, have notes ... so when the chokepoint happened, my brain could not take it. But notifications is what triggered the disruption (of a bad kind).
Hopefully it helps
This is incredible advice across the board. Would you consider writing this somewhere and submitting it as a post? I think this is valuable and worth repeating.
Let me see what I can do. Thanks ! May take me a month since I am sure I can polish it a lot more, not on how to create a deck but how to prep.
Absolutely, I think it's timeless so take your time!
Great advice. One point I’d add is to just let yourself be nervous. Once I accept that my voice will wobble and my hands will shake then nervousness starts to feel a little more like excitement.
Rehearsal works great for fighting nervousness. Just the mere thought of speaking in front of 30+ people makes my heart slightly faster, but once I have a presentation down to the minute and can go through it 100% without looking at my notes, the nervousness dies down a lot and confidence starts taking over instead.
Of course, it reverses back the second you take a step into the stage, but it gets a whole lot worse when you don't remember what to say, and once you've spoken for 4-5 minutes the confidence seemingly remembers to come back by itself too.
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.
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.
I'm sorry to hear that. If it's any consolation, people often say I act like an alien pretending to be a human. Maybe it's just the price I pay for being an inquisitive person.
> 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.
I get where you're coming from, and I agree to some extent, but I do think our tendency to weight criticism more favorably than praise (as if praise is "chaff" and criticism is automatically valuable) can be dangerous. This negativity bias unfortunately led me to adopt less-than-optimal ways of working in my younger years, because I assumed the people offering me criticism knew what they were talking about, when this wasn't always the case.
So while criticism can be valuable, I think it's worth reflecting an equally critical eye back at the person who is offering it, as upon closer inspection they may not be worth listening to at all.
> because I assumed the people offering me criticism knew what they were talking about
I feel like this is the issue, and it's everywhere, not just HN. So 'fixing' HN wouldn't really solve the problem, each individual needs to learn what criticism they can listen to VS not. In the AFK world we have the benefit of knowing people, so you can implicitly trust some of them, but on the internet you need to first calibrate your "bullshit sensor" so you know what take aways you can actually take vs not.
> So while criticism can be valuable, I think it's worth reflecting an equally critical eye back at the person who is offering it, as upon closer inspection they may not be worth listening to at all.
Indeed, I agree :) As long as this happens based on what the person wrote rather than who the person is, you'll learn to eventually get really good at this, and all the mindless criticism becomes no-ops essentially :)
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.
Your article, https://www.matheusmoreira.com/articles/babys-second-garbage... made me happy. :)
I read this in the voice and cadence of a D&D dungeon master reciting an epic tale,
It reminded me of this ad for a video game cosmetic. It had the same brought-a-smile-to-my-face energy. :)https://www.youtube.com/shorts/K9mlJMVmEOY
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!!
> “What are these?”> “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.
There's this TV series, Doctor Who. Its two most recent seasons have been produced in partnership with Disney.
The latest Doctor's era started with a Christmas special. The episode is told from the perspective of Ruby, his soon-to-be assistant, who appears to be troubled by a suspiciously consistent streak of really bad luck in her life. The Doctor is first shown as a mysterious figure suddenly showing up out of nowhere to catch a glass that Ruby just dropped at a club before it reached the floor, just to disappear a moment later without any introduction. He makes an impression of some "fairy godmother"-style character that stays hidden in the background, pops up to help Ruby and disappears immediately afterwards. Some time afterwards Ruby gets into a really serious trouble and the Doctor finally steps in to triumphant music to save the day and starts fully interacting with Ruby. Pretty common and effective way to do a build up to an introduction of a mysterious character, you'd say.
Except... there's one extra scene with him placed in between. As a yet another instance of Ruby's mysterious bad luck, a huge promo installation depicting a snowman is about to fall from a building's elevation onto the taxi she's riding in. She's completely unaware of the danger, but of course, the Doctor is there in the background to save her again; he makes the traffic lights switch faster so the taxi is already gone before the snowman falls. However, that's not the end of the scene - it appears that the snowman will now fall onto some pedestrian who now entered the crossing, who appears to be a mother with a child in a baby stroller. The Doctor rushes to push her away, the snowman falls onto him instead, though it turns out to be empty inside so he isn't harmed after all and the stroller turns out to be filled with Christmas presents rather than a baby. A policeman shows up, questioning the Doctor for a bit about what just happened there. The Doctor introduces himself in a short conversation with the policeman before he goes away.
I was quite baffled while watching that scene and once I finished that episode I kept wondering what was it about. I couldn't see the point of it, it wasn't telling us anything new that we didn't already knew about Ruby, the policeman is nowhere to be seen again either, it only seemed to diminish the later scene when the Doctor finally gets into the action properly and steals the spotlight. You can't successfully build up to an exciting entrance when you just had another less remarkable entrance already. It also felt out of place as this one moment wasn't being told from the Ruby's perspective anymore - the taxi with her inside was already far away. He still introduces himself to Ruby later on, so you could just cut that scene entirely and no value would be lost. In fact, I'd say you would actually add some value this way, as it felt to me that the episode would simply flow better without that scene.
Fast forward some time and I stumble onto commentary track of one of the episodes. Here I hear the episode's writer (and showrunner) talking a bit about how the collaboration with Disney goes. He says that he has plenty of creative freedom and Disney is rather off-hands, but they do come back with some notes from early screening panel testing that he isn't required to act upon but which he considers useful regardless. As an example, he mentions that the Christmas special episode got some early feedback from Disney during production - it took quite some time for the episode to introduce the main character and the test audiences were getting impatient, wanting him to be introduced earlier. The writer then concluded that he decided this feedback makes perfect sense, so they did late shoots to include an additional introduction scene - the one I described above which existence baffled me while watching. This explained everything: the Doctor's triumphant entrance was clearly meant to be the moment of his big reveal, but now it just wasn't anymore, all because of applying seemingly reasonable feedback that was meant to make the episode better.
This is kinda what applying LLM feedback to your writing feels to me. You see some argument being made and it makes sense when you think about it, so you apply the proposed changes, forgetting about what made you write it the way you did it in the first place. In the end, the result gets worse for one reason or another. You "fix" things that were actually load bearing and allowed the reader to connect with your thoughts better.
> 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
Sure thing.
https://www.matheusmoreira.com/articles/babys-second-garbage...
I just skimmed it and dont see how anyone would come to a conclusion of schizophrenia/mental illness.
However, I only skimmed it because I REALLY did not care for all the prose etc... It was literally unreadable/incomprehensible (without investing considerably more effort). This seems to echo one of the comments in the original HN discussion.
But, if it made you happy to write and re-read it, then I'm in favour of it. Keep doing your thing. Evidently some other people like it as well.
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
I think this is the original discussion:
https://news.ycombinator.com/item?id=47612331
Most of the comments were positive but negative ones always hit harder for some reason.
That was epic and I couldn't stop reading.
I'm floored people told you that you had issues because of that article. I'd ignore them and forget all about it.
That was fantastic. Vaguely reminded me of: https://0x5f37642f.com/
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
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!
<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.
Streaming sites and shopping carts are used by millions of people, but casually after work, maybe twice a day.
LoBs are used intensively for hours on end in a busy work day, and most people's livelihoods depend on them either directly or indirectly. You grow into them. Muscle memory used to be an actual UI design goal, back when TUI's were the most common LoB interface. Not so much anymore when everything is web app and you click through the horrid UI slowly with your mouse pointer, and repeat this identical task 200 times in a day.
edit: We naturally develop a muscle memory even for the worst LoB. But they are not designed with this in mind. If they were, they wouldn't move that one critical pixel around in a mouse driven app.
> 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
> > It's kinda like people complaining about Space Launch System, why aren't we using Saturn V or an improved version of it.
Because the SLS uses left over Space Shuttle engines. Once.
The Space-X approach is to use 33 Raptor engines.
> Because the SLS uses left over Space Shuttle engines. Once.
The reused RS-25s aren’t the same as the ones that flew on the STS-1. STS-1 used the original RS-25, Artemis uses RS-25D, and will in future use the new RS-25E.
In the same way, if Saturn V survived to the present, we wouldn’t be using the original F-1s/J-2s any more, we’d be a using significantly enhanced versions-and the originals would be infeasible to manufacture due to component availability changes
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.
But, but, they're digital natives, oh course they know all about computers. /s
I get that. I used to be able to overhaul a VW beetle on the side of the road with regular tools. A couple of years ago my car's transmission's computer went out on the interstate. I couldn't even get a useful error code. The shop down the street didn't have a high enough end device to talk to it. While the dealer was able to figure it out; it took nearly a month to get the replacement part. I'm car semi-literate.
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
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
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.
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.
Julia is a fantastic writer herself. I've long followed her work, and always been impressed with how great she is at distilling information.
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.
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.)
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.
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.
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.
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.
https://blog.plover.com/math/PM.html
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.
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."
On average, you nailed it.
(<https://old.reddit.com/r/Jokes/comments/1ko9l3h/three_statis...>)
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.
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.
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!
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.
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.
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.
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