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

361–370 of 455 posts

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

#361

Post by CobrastanJorji »

csallen wrote: post #30

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

I remember being in a raid guild. The guild leader was this random 18 year old kid. I remember noting that this kid was expertly herding cats, many of whom were much older professionals, with absolutely zero direct authority, across multiple timezones, and getting them to not only agreeably distribute valuable loot, but also coordinate them through intricate boss dances and more intricate event scheduling. I thought it was a real shame that this wasn't direct evidence that he should be hired into a people management role immediately.

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

#362

Post by Eric_WVGG »

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.

Apple documentation reminds me of an argument I got in with an elementary school teacher over a textbook… it went on for weeks

> A prepositional phrase is a phrase with a preposition in it.

> A preposition is a word in a prepositional phrase.

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

#364

Post by zahlman »

toyg wrote: post #299
bonoboTP wrote: post #251

Earlier quoted context omitted.

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.

That's something I came to accept as well - deeper understanding will only come from challenge. Unfortunately, there isn't always the opportunity to let people fail, and that opportunity is definitely not in a set of reference docs.

> and that opportunity is definitely not in a set of reference docs.

Okay, but GP is talking about tutorials, which are a completely different form of documentation.

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

#365

Post by zahlman »

Nab443 wrote: post #315
BrouteMinou wrote: post #98

Earlier quoted context omitted.

Yes, more of this! I am a big fan of the "clone, F5" and it should run. If specific steps are required, I put that in a setup.ps1, and the details in the readme.md. If the project has external requirements, I put a link to the repos, which should all be... "clone, F5"...

When I type F5, my terminal writes "~" but nothing happens, what did I miss?

In case you weren't attempting to make a point through irony, GP appears to be using "F5" informally as shorthand for "instruct your IDE to attempt to build and run the code". Presumably, that kind of documentation wouldn't normally literally say "F5" there unless a specific IDE had already been prescribed. The point was simply that the user shouldn't be required to do anything manual to set up the code, when starting from scratch, except perhaps to authorize the automated setup procedure.

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

#366

Post by fingerlocks »

shakna wrote: post #306
fingerlocks wrote: post #291

Earlier quoted context omitted.

That’s just a C enum interfaced in Swift. You can’t instantiate it, and it has no methods or any kind of functionality. It’s effective a list of numbers. What are you expecting the documentation to say here? It will make more sense when you find where it’s used. Edit: First link on the bottom explains exactly what it’s used for. https://developer.apple.com/documentation/avfoundation/retri...

struct AVMetadataKeySpace - a unique unit representing each of the metadata key spaces supported by AVFoundation.

? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me.

There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.

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

#367

Post by AlienRobot »

aDyslecticCrow wrote: post #184
beklein wrote: post #169

When writing documentation, you need to establish a baseline of required knowledge and skills for your audience. You can choose any level, but deviating too far above or below that baseline will inevitably frustrate some readers. When this happens, you can either make excuses or focus on solutions. Problems can be difficult, but with modern tools like AI systems, Google, or even books, it has never been easier to ove…

> you need to establish a baseline of required knowledge and skills for your audience So many guides for setting up like... "control system simulation" or "industrial automation compliance test-bench" start with "double click the exe and press next". Baseline for expected knowledge for the user of the guide is SOOOO important.

"What is an exe?"

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

#368

Post by angiolillo »

zahlman wrote: post #359
angiolillo wrote: post #246

Earlier quoted context omitted.

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

I mean, if the test user can't figure it out at all, how is the rest of the UI/documentation supposed to get evaluated?

Great question!

If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as:

1. Participant expresses extreme frustration or gives up

2. A couple minutes have elapsed from the first failed attempt

3. Participant unsuccessfully attempts three distinct approaches

If the test reaches one of your cutoffs then the interface/docs have failed the task and the moderator can skip to the next task or question. Sometimes they'll also offer to show the participant the expected solution or explanation.

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

#369

Post by delecti »

peterfirefly wrote: post #350
hayleox wrote: post #345

Earlier quoted context omitted.

Not quite what you're talking about but this Apple doc page has always amused me: https://developer.apple.com/documentation/contacts/cnlabelco... I have to assume that there exists some language where that relationship is described in one word, but it hurts my English-oriented brain.

There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".

And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.

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

#370

Post by zahlman »

magic_hamster wrote: post #290

You are a beginner for a short time. Once you get your bearings you will beg for more resources beyond a beginner tutorial. A serious framework, language or any other tool geared towards production, has to be supported by docs, tutorials and (where possible) a community of people actually deploying this stuff, possibly at scale. I wonder if we'll see another post next year when OP realizes there's virtually no conten…

> You are a beginner for a short time.

If you have the right mindset and consciously seek to progress past it, yes.

I can recall seeing people spend years on concepts in a way where I really couldn't rule out the possibility of dedicated trolling. I remember one who would repeatedly ask about fixing problems with code examples using various advanced (at the time) graphics APIs while clearly missing several fundamentals about writing code in the language. And who also seemingly refused, the entire time, to adopt the proper spelling of "variable", despite it being corrected by multiple people in every discussion.

Post reply on HN