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

241–250 of 455 posts

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

#241

Post by Aaargh20318 »

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.

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this).

    setFontSize(float): sets the font size.
Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I expect for fonts (points).

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

#242

Post by sylens »

So many tutorials will just assume everybody's system, workflow, tooling, etc. are exactly the same as theirs. How many tutorials start with just "brew install"? It wouldn't take much time at all to say "You can use Homebrew to install this - here is a link to install Homebrew for macOS and Linux"

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

#243

Post by heelix »

We did something similar with 'prod' code reviews. We started including a couple of the more junior folks in a pre-release review that was mandated. Intent was to say fine, id tech debt, or pull the andon cord if something was missed that would impact prod. What came out of it were their questions - which almost always was translated into an ask for documentation for that bit of code. The secondary bonus was they learned the questions that would be asked of the people who were merging.

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

#244

Post by ozim »

rdtsc wrote: post #70

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

For me the issue is some people expect everything to be simple/easy to do without any prior knowledge and then claiming it is not really hard but you are gatekeeping and only if you could explain it easier they would definitely grasp it instantly.

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

#246

Post by angiolillo »

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 people who made the UI/docs to stay on mute or on the other side of one-way mirror.

But I'd still suggest learning the "just watch" technique. If you master that and wish to take the next step, look up "think-aloud protocol".

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

#248

Post by bonoboTP »

Aaargh20318 wrote: post #241
imgabe wrote: post #225

Earlier quoted context omitted.

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.

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this). setFontSize(float): sets the font size. Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I exp…

In similar cases (maybe not exactly here), I suspect the author also didn't know and didn't care to look it up and just wanted to tick the box that it's now documented.

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

#249

Post by bonoboTP »

derf_ wrote: post #203
Schiendelman wrote: post #188

Earlier quoted context omitted.

For most public documentation, you don't get to pick your audience. You think you'll have people with certain experience, but then it turns out you're wrong. Usually a lot of the time. And even when you're not wrong, having the steps essentially from scratch listed out reduces the number of times people get stuck, because they think about things they may have missed.

I cannot tell you how many times I've had to go through 30 hyperlinked pages of fluff explaining universal basic concepts before finding the five sentences I actually needed (buried in five different places). And just as many where people explain in detail exactly how to do foo with bar without explaining why I would want to do foo in the first place and what a bar even is.

This really is one of those things that AI can improve, and already improves today.
Post reply on HN