Live data from Hacker News

Write for One Person

wizardzines.com

51–60 of 82 posts

Re: Write for One Person

#51

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." "T…

That is truly awesome. Good on you.

Re: Write for One Person

#52
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.

Re: Write for One Person

#53

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…

> 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

Re: Write for One Person

#54

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…

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 havin…

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.

Re: Write for One Person

#55
post #33

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." "T…

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

Re: Write for One Person

#56
post #33

Earlier quoted context omitted.

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 ther…

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.

Re: Write for One Person

#57
post #7

> 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…

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 th…

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.

Re: Write for One Person

#58

> 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…

> 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.

Re: Write for One Person

#59
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.

Re: Write for One Person

#60
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.
Post reply on HN