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

341–350 of 455 posts

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

#341

Post by mrguyorama »

pyjamafish wrote: post #238
marklubi wrote: post #43

Earlier quoted context omitted.

> Beginners have to be nurtured through lots of context that builds up slowly. My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night. I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.

Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25. https://openjdk.org/jeps/512

I actually think the inscrutable Main method in java has some value. As a kid, I loved to know how things worked and always did things like read instruction manuals and read ahead in school textbooks. I wanted to know everything about anything, and I wanted to know how it worked from the bottom up.

The java main method taught me "This is abstraction, an important concept in programming. You won't always know how all the magic works all the time"

It taught that you have to deal with black boxes.

Also, I never saw it cause problems in CS101 classes, because the kids curious enough to want to know something their professor didn't explicitly talk about were usually the ones who would do fine at learning all the parts of it.

The kids who struggle with programming never seemed to have problems following "Just write your code here, you will learn more about it later"

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

#342

Post by lacoolj »

Sounds like you may not be ready to read this tutorial just yet. Maybe get more experience in the terminal, and read docs on specific languages (elixir has good ones, for instance) or take a hands-on course (like Codecademy Javascript, etc).

Then, once you have more experience, you can go back to that tutorial and try reading it with more polished eyes.

What you've posted is the equivalent of me taking a new interest in cooking but applying to culinary school. If I haven't cooked in a real (production, high volume) kitchen, it's all gonna be Greek, overwhelming, and turn me off.

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

#343

Post by wang_li »

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.

The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to consume the documentation and it's not a documentation failure that this is true.

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

#344

Post by bluecheese452 »

polymatter wrote: post #158
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…

Maybe being able to follow a set of (seemingly silly) instructions should be part of the interview/onboarding process. And emphasised at job performance time.

Problem is a lot of times silly instructions are silly because they are wrong. Like why did you turn left and try to drive through that river? Those instructions assumed a bridge was there but it washed away 10 years ago. A new bridge exists, you can see it, obviously take that one instead.

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

#345

Post by hayleox »

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.

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.

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

#346

Post by sim7c00 »

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.

then how would you descirbe a nargfargler?

dont say.. boop?!

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

#347

Post by gregates »

parpfish wrote: post #296
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

My first ever software developer job, I was hired with basically no knowledge or experience to learn (I was very lucky). I knew MS-DOS command line pretty well from my childhood, but hadn't ever used POSIX. I was given a macbook air and some docs to follow.

Trying to follow the docs, supplementing with a lot of googling, I somehow managed to remove the tar program from my system. This broke literally everything. Had to stop halfway through the multi-day process to do a clean reset and start over from scratch.

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

#349

Post by gertlex »

devoutsalsa wrote: post #104
gertlex wrote: post #69

Earlier quoted context omitted.

This issue with READMEs in particular has driven me nuts for the decade I've been doing ROS related robotics stuff. So many repos where the only surface clue (i.e. before diving into the code) of what it does is your interpretation of its name. But I'm pretty sure it's universal, like you allude to. And not just open-source; but at work, too. I feel like I'm the only one in my company that makes PRs to edit the READM…

Lately I’ve been asking Cursor “what does the program do?” Was actually pretty helpful as a starting point.

Oh yeah, definitely. Great for my own "throwaway" or rushed projects that I want to revisit, too :D

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

#350

Post by peterfirefly »

hayleox wrote: post #345
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.

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".
Post reply on HN