Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

anniemueller.com

Post reply on HN
Print view View original

251–260 of 455 posts

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

#251

Post by bonoboTP »

nomilk wrote: post #48

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

I'll go against the grain and say that fumbling is how you learn. The easier it is to get to the end of the tutorial, the less you learn in the process. If you learn math from a bad book, you have to organize your own notes, to untangle the mess. If it's laid out all neat and clear like a straight highway, you never wrestle it out with the concepts and you don't learn.

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

#253

Post by mschuster91 »

angiolillo wrote: post #246
nomilk wrote: post #48

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

> Do not speak to them, certainly do not help, just watch. Sounds simple, right? I ran usability tests at a past company and have seen people who were incapable of blurting out explanations, pointing at the screen, even audibly grunting or whining to themselves when the participant made an incorrect guess about what something meant. One even grabbed the mouse. Having a neutral moderator can help as it allows the peop…

> You can also record it to show them later, but for various reasons it doesn't resonate quite as strongly when it's not live.

Yeah, because it's wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts. It's fine if I actually have the time to explain to some Gen Z kid how Ctrl+X/C/V works, but being forced to sit around and watch someone with that level of non-understanding of how a computer works when I got a full backlog of shit to do is just agonizing.

With a video recording, I can at least go forward and see where they actually have problems with stuff that is in my influence and skip over the utterly boring moments that are just wasting my already limited time.

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

#254

Post by teddyh »

throwaway2037 wrote: post #186
jen729w wrote: post #125

Earlier quoted context omitted.

Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written . Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions. I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. I…

Joel Spolsky famously wrote in the year 2000: > Users don’t have the manual, and if they did, they wouldn’t read it.

— https://www.joelonsoftware.com/2000/04/26/designing-for-peop...>

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

#255

Post by teddyh »

ninetyninenine wrote: post #220
nomilk wrote: post #48

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

LLMs have mostly eliminated the need for this. They are quite good at explaining things.

Correction: They are very good at writing seemingly-good explanations. The explanations may or may not be correct.

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

#256

Post by mschuster91 »

skydhash wrote: post #180
maxloh wrote: post #138

Earlier quoted context omitted.

I think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field. In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whol…

Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)

> Usually you look for code examples or a guide for learning how those work

... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.

The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.

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

#257

Post by the__alchemist »

This is spot on, and can apply to anyone branching out into a new area. I will add this concrete piece of advice that can simplify things:

Don't ask the user to install tools or use ones that are not core to the topic. I still have a bad taste in my mouth from the 2 Scoops of Django tutorial after getting stuck installing VirtualBox, Chef, and Vagrant. The solution was to just not use them, because they don't have anything to do with Python, Django, or making a web server.

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

#259

Post by vrighter »

peteforde wrote: post #45

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…

There was a project posted here once that didn't even bother saying what the thing even was!

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

#260

Post by FranzFerdiNaN »

skydhash wrote: post #189
sebstefan wrote: post #142

Earlier quoted context omitted.

That changes everything It would be crazy for a beginner developer to expect a technical post made for other developers to dive into explanations of What's Hoobijag/jabbernocks/ABCDE++++/Shoobababoo/a shamrock portal. We've all been through that phase where you have to google the words you don't know.

Also a lot of beginners skipped a lot of (cultural?) foundational knowledge. A basic understanding of filesystem, network, and os commands would go a long way for communication efficiency. Instead, they’re cargo-culting.

There really is a huge gap between a programmer and being capable at using a computer. I work in the data space and while im good enough for my own needs with Python and grew up in the 90s with MS-DOS and Windows 3.1/95, the second i have to use something that is build by and for programmers i too end up feeling like the blog post describes.
Post reply on HN