Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- 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.by TonyStr
- 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.by chabad360
- Writing for "you, but three years ago" is excellent advice.by simonw
- Totally! I like the bit about writing for a colleague, because this gives you a much more relatable concept I think.by ryanisnan
- "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.
by dredmorbius - 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.by Shellban
- 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.)
by neilv - 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.
by chrishill89 - 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.
by Animats - Julia is a fantastic writer herself. I've long followed her work, and always been impressed with how great she is at distilling information.by ryanisnan
- 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
by Jap2-0 - 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 Vonnegutby PyWoody - 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.by annzabelle
- > 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
by skissane - 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.
by crooked-v - 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.
by EvanAnderson - > 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.
- <3by munificent
- 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 worldby mettamage
- 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!by frogulis
- 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
by jordwest - > 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.
by ffsm8 - 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.
by mediaman - 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.
by maplethorpe - 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.
by Syzygies - Great story. Thank you.by ustad
- That is truly awesome. Good on you.
- Is there a link to the "shuffle seven times" talk?by monkeywork
- 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.by dasyud