I wrote an article that never fails to put a smile on my face every time I read it. I felt like I had finally found my own voice. Ran it through Claude and it told me to tone it down a bit, but I ignored the advice and published it anyway.
The article caused people on HN to say I had issues. They weren't exactly wrong, but still. Be careful with what you publish out there. Warm reception is never guaranteed. My one consolation is the fact Bob Nystrom apparently liked it.
I get stuck when I try to post on social and my brain fills up with all the random people I know that have commented or complimented a post. The problem is there are wildly different expectations of what I post. Is anyone else dealing with this?
Lately I've decided to write for ME. What do I want to write about? That has made it a lot easier to get unstuck. That and not looking at the views, likes, etc.
I 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.
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!
Seriously! Every music theory blog post and video is like this. They're going to explain something like modes or maybe altered dominant scales, and they start out explaining intervals. Seriously stop, not from the beginning again! That's not your audience.
I'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.
"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.
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.
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.
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.)
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.
>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.
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.
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 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.
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've always written my blog for myself. I keep it as a record of what I'm working on, I suppose, or what I'm interested in. I was mildly surprise to find I had 279 blog posts on https://tech.stonecharioteer.com. I only ever write for myself. Whenever I try to write for an audience, I am not satisfied.
I 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.
29 comments
[ 4.0 ms ] story [ 41.3 ms ] threadI 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.
Lately I've decided to write for ME. What do I want to write about? That has made it a lot easier to get unstuck. That and not looking at the views, likes, etc.
I 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.
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
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.
- 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
Then, I have a few products that have maybe 10 users.
Too niche is an issue.
> 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.)
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.
Oh.
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.