Most devs write docs like aliens. Time to send them back to elementary school English class.

This is gold

Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience.

And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago.

This is why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.

And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.

The funniest part, lol

    it might be in library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file.

But is this tutorial meant for a non developer to read? I would imagine a linguistic psychology tutorial would have the same effect on a dev written by an expert.

I followed this tutorial but ran into an issue where shamrock portal kept crashing. When I checked the logs, I found it would start a beep but never finish a boop. After a few hours of Googling I discovered my Debian 12's Klingon troglodyte emulator had a known centipede reported in 2013 that's never been squashed because hoobastank 34.100-6x00 actually requires it, and Debian can't move to the newer version of hoobastank without a major gLibc upgrade. I got shamrock talking after compiling the compatibility shim for single-threaded pintafore and migrating from Debian to Fedora 75bit, but then the fistifunk socket closed! A few more hours troubleshooting and eventually figured out the root cause: The Snarfus node's DNS resolver was down. Turned it back on and everything worked perfectly.

I guess many tutorials are not made for absolute beginners and they have assumed you have learnt the basics before jumping into their topic. For example, if you never learn programming and set up an ide before, it has no way you can learn OpenGL as your first tutorial, and all the syntax and commands will look alienated.

This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.

One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more accessible.

Occasionally people will complain that you're being verbose and adding detail that they didn't need but in those cases you can usually just say "oh, that's just in case a [junior|manager|customer] sees it." People don't mind if you flatter them that the explanation was for other people.

It applies as much to development as it does to investment reporting, people management, delivery management, etc,

These days I dump code into an LLM, ELI5. Then ask it to tell me logical chunks and overall structure. I then go from there.

How I, a professional developer of 15 years, read the prose-heavy README you, a developer, wrote on your repo.

All docs should start with examples. Some docs would be better if they ended right there.

When I was at the head of the jailbroken iPhone ecosystem, I put together a tutorial for how to get an SSH daemon set up on their phones. I put a lot of effort into making it something that anyone could follow, step by step, and achieve the result, making sure to skip no steps, assume no knowledge, and with screenshots showing the interface.

I soon thereafter received an e-mail from someone saying that they had excitedly followed my tutorial and found it very easy to follow; but, they had now gotten to the end of the instructions, were staring at some text that said "mobile@iPhone ~$ " (or whatever the default bash prompt was; I do not remember) and they did not know how to proceed.

I had similar experiences over the years, and I had a realization at some point: if you provide someone detailed step-by-step instructions for how to find the dragon, part of the UI/UX of the tutorial should be that you don't actually feel comfortable following it if you should not be doing so: the difficulty of the path must scale with the goal.

This is similar to real-world affordances, FWIW: if a user should not be opening a panel unless they are ready to do maintenance, yes, don't go out of your way to make it hard to service without permanently damaging it (that's evil), but, maybe, screwing the panel shut is more appropriate than providing a pull tab, due to what the latter implies.

A lot of users find this annoying, because they think they want to do X, and they just need better step-by-step instructions... but, that's just not how the world works: a lot of times, what you need to do to do the task is, in fact, a basic knowledge of the entire system, sufficient that you will need a fraction of the instructions (if any).

On the other side it causes another problem, BTW: if you make instructions that anyone can follow--including people who probably aren't at the level where they should do so yet--you also end up with instructions that are more difficult to follow for the people who should be doing so, as they are extremely verbose and often narrow in their scope.

It also sets up perverse incentives to try to make the instructions even easier to follow, well past the level of easiness the task should actually be at, which, again, causes problems for the people you actually want following the tutorial: if you find yourself creating little docker containers to avoid saying "install a compiler"... no.

It's people sharing with others of equivalent skill. Use an LLM to adjust to your skill level. The times I write this it's to document something that worked. There's no guarantee it's what will work for you. You're supposed to translate it. So it's not really written for you.

Most technical writers (and communicators in general) have an insufficient appreciation for the curse of knowledge.

This takes me back to running a World of WarCraft guild as a teenager.

We would organize "raids" maybe 3 to 4 times a week. It involved getting 40 of our guild members from all over the world to sign on at the same time, and spend hours facing off against dragons and other monsters inside dungeons. It was the most fun I'd ever had in a game, but it was also instructive. The battles were famously difficult and required a ton of coordination and strategy, and even a small mistake could get everyone killed. So our policy was that everyone in the raid had to sign onto our Teamspeak server, which was basically an audio-only Zoom call where my appointed officers and I could give orders and dictate strategy.

I very quickly learned an important lesson in communication: assume the worst. Surprisingly (to me at the time), most people who don't understand what you're saying won't stop you to tell you they didn't understand. And so I came to live by two rules:

1. If it's worth saying once, it's worth repeating. Assume people are only half listening, that they're distracted, that they're not paying attention.

2. Don't assume people know what you know. In fact, while talking, keep a second thread running where you explicitly ask yourself, "What am I saying that my listener might not know?" Then explain it.

The more I followed these rules, the better we did on our raids.

But even long after I stopped playing WoW, both of these rules have been helpful. Especially the second one, which helps overcome the curse of knowledge -- the phenomenon that occurs when a person who has specialized knowledge incorrectly assumes that others share in that knowledge.

Thinking about the curse of knowledge when communicating basically becomes second nature after a while. And then it becomes obvious when you observe other communicators who don't care about the curse of knowledge. They confidently launch into stories using obscure terminology and acronyms that nobody understands, without a care in the world for their listeners' understanding, they don't notice at all that nobody understands.

Most tutorials aren’t for non-developers. They’re not for developers, either. They’re a bunch of prose I want to skip, and then I finally get to the steps I’m really looking for, but the author left one out, or assumed some weird development environment or IDE I’m not using, and I have to give up and go back to Google again.

The problem is that writing is hard, because it’s for people outside of your head, while you’re inside of it. As toddlers we learn that our senses aren’t immediately accessible to other people, but many of us never master the art of remembering that knowledge and experience inside our heads isn’t available to you, the reader, until we write it down.

Oh, and maybe if folks thought “cookbook” instead of “tutorial” when they’re writing, the result might be organized better for the rest of us to use, and less likely to become useless after the next point release.

Code samples. This is what’s missing most of the time. Even if you encounter esoteric jargon, if they give a few examples, it’s pretty easy to decipher. Even big companies like Google give code examples in multiple languages.

It's always a problem that you forget what you use to not know.

When I first started writing some internal docs/tutorials at work, I was new to Linux. So I generally took the time to include tangents into explaining fairly basic Linux concepts, because they were new to me. They were rough edges I had to get past so I wanted to help others do the same.

Five years and a shit load of Linux experience later, I don't do that anymore. That stuff has become so second nature to me that it just doesn't even occur to me anymore. And I just don't have the damn time. If I had to stop to explain what cat or sudo or | mean in every doc I write I wouldn't have time to get anything done.

i started frequenting hackernews because i knew that tutorials written by developers would start making sense if i just kept trying to read them. it worked!! took a few years though.

I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy.

What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.

Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.

I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.

It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.

Can't recommend this approach highly enough: have someone with minimal expertise go through your docs with the goal of achieving the goal of the docs. Sit next to them or screenshare. Do not speak to them, certainly do not help, just watch. Watch them fumble. Watch them not know what to do. Watch them experience things you (the author) didn't, because you already had xyz configured on your machine and you forgot users won't have it. (even watch them pretend to know what they're supposed to do when they don't really).

If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.

I've used FAANG docs that don't come close to passing the above criteria.

I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.

This mirrors my experiences 20 years go, but I actually appreciated it because it pushed me harder to learn the dev arcane languages.

Most docs I read have their prerequisites spelled out.

This is the version of this OS with this plugin that this guide is written for.

So when I find that, inevitably, something has moved, I can figure out how my setup differs and search for the difference.

If you cant stand up the prerequisites, then the doco isnt for you, you should be searching for documentation on how to stand up the prerequisites.

Straight from "A Clockwork Orange".

The title is misleading. Here is the actual title:

    "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"

So, she is not a beginner developer, but a beginner at using your software.

I tend to write overly-long tutorials [0]. They are usually aimed at developers that reflect my own capabilities, but about a decade ago (in experience, but not tech). I write about relatively specific, advanced topics, aimed at folks with a baseline level of understanding.

I use a lot of well-tested code samples.

Writing for true newcomers, is very difficult, as there’s a lot of context-building.

My code documentation[1], on the other hand, is written for folks at my level (I basically write documentation that I want to read).

[0] https://littlegreenviper.com/miscellany

[1] https://littlegreenviper.com/leaving-a-legacy/

The title of the blog post currently is:

> How I, a non-developer, read the tutorial you, a developer, wrote for me

The HN title is:

> How I, a beginner developer, read the tutorial you, a developer, wrote for me

Those are different things. A "non-developer" reads as someone who isn't supposed to understand any of this. I am imagining a human resource person, a customer completely unfamiliar with internals, someone from a completely different area of expertise. They shouldn't have to know what snarfus are, or how to fisterfunk the shamrock portal. In that case yes, let's mock the developer for completely missing the mark with a 6 paragraph long joke.

A beginner developer, however, is someone completely different. This is a person who will eventually have to juggle snarfus, and as unfortunate as it may be, even need to fisterfunk the shamrock portal. It is partially on them to put some effort into figuring out what fisterfunking is, and how it applies to the portal. If they are particularly good, after figuring out what those things, they may even volunteer to update the documentation as to make it easier for the next beginner developer to understand it instead of replying with a 6 paragraph long joke about it.

This hits home, and not even relegated to software. My partner decided to learn to ride a motorcycle during the pandemic. I’ve been riding in some form or another for more than half my life. In the first minutes of attempting to explain the procedures, I immediately realized there were years of involuntary movements and coordination I failed to articulate because it wasn’t a part of my mental model of the process.

Needless to say she signed up for a professional course, got the license, and we’ve travelled nearly 10,000 miles together since!