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

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.

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.

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.

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.

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/

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,

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.

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"

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.