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

291–300 of 455 posts

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

#291

Post by fingerlocks »

multifasciatus wrote: post #282
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.

AVMetadataKeySpace A structure that defines a metadata key space. source: https://developer.apple.com/documentation/avfoundation/avmet...

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

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

#292

Post by euroderf »

ctkhn wrote: post #265
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…

It's crazy how bad most onboarding docs are for corporate teams. I think it's a great first look the culture and how much of a hassle the role will be. The last three teams I've joined have been brutal with how little was documented or how out of date the docs that did exist are. I've had to spend up to two weeks tracking people down to find out what access group I need for our logs, deploy pipeline, etc. and I end u…

A technical writer's first task is to start the document that onboards the next technical writer.

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

#293

Post by euroderf »

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…

Ask the guinea pig (read: victim) also to think aloud.

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

#294

Post by 2b3a51 »

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…

Perhaps in addition to a description of the expected audience, it might be an idea to list some assumptions made about the reader? e.g. has installed software previously, confident with bash commands, &c

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

#295

Post by hobs »

angiolillo wrote: post #284
mschuster91 wrote: post #253

Earlier quoted context omitted.

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

Before I saw your response I removed this sentence from my post as I realized it was not central to my main point. However, I still agree with it and am happy to explain why. > wasting my time having to watch people who literally have never heard of something as basic as keyboard shortcuts First it depends on whether the audience for your product includes people who do not know keyboard shortcuts. If that's not your…

It's like how expert athletes often watch videos of themselves or competitors (when applicable) to understand the nuances of their play - once you understand something very deeply the small things start to matter more, until they dominate the game.

If you are a master of UI/UX and you are observing a user doesn't go through the paths you've created its an opportunity - you might be able to learn something that would make your approach more successful across a host of different users that up to this point you clearly are not winning the game against.

If you take an antagonistic approach and curse the idiot for making you watch you have not even put on a jersey yet.

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

#296

Post by parpfish »

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…

Reading through bad setup docs is 10x more stressful when they are part of new employee onboarding.

I’ve always advocated for new employees first contributions to be fixing problems they had in these setup materials. They are coming in with fresh eyes and no context so they are the best possible reviewer

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

#297

Post by rdtsc »

wonger_ wrote: post #213
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…

FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer." The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demogr…

> FWIW, I submitted it as "non-developer" but a moderator seems to have changed it to "beginner developer." The author is a non-technical blogger, and she probably has to navigate lots of technical guides in order to fiddle with her website or CSS. I think a more relevant discussion would be about making website publishing easier for everyday people, or about the lack of documentation written for that particular demographic. But HN took it in a different direction, which is fine.

That makes sense, thanks for clarifying. That's why made sure to point out the difference to avoid confusion. I think folks, including myself have been on all 3 sides of the situation: as a new developer who is supposed to learn confusing terminology, non-developer who is thrown a bunch of jargon to look at from a completely different domain that's not their responsibility, and the developer who write stuff and then wondered why other can't comprehend the "easy" tutorial.

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

#298

Post by CarpeQueso »

On the flip side, it's taken me a long time to break my skimming habits and read slowly when I'm a novice in a new area. Especially with math or software engineering, it's often necessary to stop at each word I don't understand, unpack it, and gradually build a scaffolding for myself. This is very slow, but it pays dividends extremely quickly.

As a rule of thumb, it seems like skimming is useful if one already have a good familiarity with a subject and the content is slotting into an existing mental framework. However, when that's not the case, skimming gives me the feeling that I've learned something without much real progress.

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

#299

Post by toyg »

bonoboTP wrote: post #251
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.

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.

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

#300

Post by MarkusWandel »

I call it "Kindergarten speak". People at the highest level of technical expertise sometimes have it, where they can patiently, and in understandable terms, explain to the most junior (but interested) party so the stuff sticks.

Others, while extremely nice and helpful, just don't "get" that their advanced jargon or, in my workplace, advanced mathematical language/notation, however elegant for themselves, is a huge hindrance for those not as versed in the art.

So if I, personally, say someone can explain something in kindergarten speak, that's the highest compliment. The more advanced lingo/notation stuff can come later, once the explainee has the big picture.

Post reply on HN