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

221–230 of 455 posts

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

#221

Post by 4pkjai »

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…

We do this in game development .

Watch someone play the game for the first time. Don’t interfere. See if they can figure out how to play.

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

#222

Post by jrs235 »

acuozzo wrote: post #24
onion2k wrote: post #14

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…

> If they do know, and you tell them, then you've only really confirmed what they already knew. Not necessarily. This opens you up to accusations of engaging in "mansplaining" which has broadened in definition over the years. In addition to this, it opens you up to being thought of as a "know it all". It's far safer, as far as office politics are concerned, to put on your coworkers the burden of asking you to clarify…

Would asking them if they already know or would like something explained be the best thing to do (rather than assuming one way or the other)?

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

#223

Post by leokennis »

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 absolutely love this approach. It is in the spirit of https://1x.engineer/ and it should be applauded.

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

#225

Post by imgabe »

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 seem to have this problem a lot with Apple’s docs. So much of it is like

    Nargflargler: Flargles the narg
You need to do something besides repeat the name in the definition.

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

#227

Post by phil294 »

econ wrote: post #214

What it should look like: Have a bunch of checkboxes at the top, one for each buzzword, each technology and all other things a 12 year old wouldn't be familiar with. You check which you think to be familiar with and all other things unfold a short description with links to similar interactive documents. Each section comes with 1-5 star rating for how well the reader understood your explanation. Then you gather the da…

This is a nice idea, but looking back at how not only documentation, but also UX in general has not improved the slightest over the last decades, it's fair to say the only way we'll ever get close to anything like this is by leveraging personal LLM assistants, unfortunately.

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

#228

Post by Lalabadie »

aDyslecticCrow wrote: post #181
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…

Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.

I'm a senior designer who often contributes to front-end code when it's convenient for my client.

Fixing and updating the README when I join a new team and set up their dev environment is always extremely well-received.

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

#229

Post by analog31 »

ocimbote wrote: post #88
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…

Any kind of documentation has a target audience. Your test is very valuable if and only if the target audience is a total beginner. Of course it's still very hard to write good documentation even if you have identified your target, but having someone totally illiterate on the subject matter review your documentation is as useful as if I'd have to review a PhD thesis in quantum physics. It just doesn't make sense (tru…

The experts are likely to be skimming and interpolating your doc, so they'll get through it but you won't know why. You won't know if your doc works, or if it even addresses the subject matter. This is also true of academic papers.

My mom taught CS in the 1980s, and told her students on day one: "Computers are stupid, they will only do exactly what you tell them to do, not what you want them to do." Program code is, in a sense, a tutorial for an utter beginner. The benefit of coding is that you can do the "beginner test" over and over without wasting anybody's time, so you know that the computer will get through it. But an expert (including yourself) might read that code and never see that it does or doesn't work.

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

#230

Post by wouldbecouldbe »

imgabe wrote: post #225
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 seem to have this problem a lot with Apple’s docs. So much of it is like Nargflargler: Flargles the narg You need to do something besides repeat the name in the definition.

Or with Xcode, go to fargler settings click on narg screen. Took a year just to figure out most setting screens
Post reply on HN