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

141–150 of 455 posts

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

#141

Post by mike_hearn »

devjab wrote: post #80
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.

> Had to explain to him public, private, internal, and also static the other night. Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to se…

Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean.

Static methods are useful for namespacing, e.g.

    var instance = SomeThing.fromString("...")
In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion.

Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.

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

#142

Post by sebstefan »

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…

That changes everything

It would be crazy for a beginner developer to expect a technical post made for other developers to dive into explanations of What's Hoobijag/jabbernocks/ABCDE++++/Shoobababoo/a shamrock portal.

We've all been through that phase where you have to google the words you don't know.

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

#143

Post by yoz-y »

I’m not doing this either but: ideally tutorials should work on a very well defined environment (clean install, VPS with X setting, application deploy at version X with plugins at versions A, B, C)

Then they should have a unit test. And a passing status. The problem with most tutorials is that they simply rot. So many times they tell you to do a command with a flag that doesn’t exist, install two incompatible packages or click a button that isn’t there.

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

#144

Post by wraptile »

This is primarily the reason why I stopped writing books and started making tutorial websites. There are so many interactive tools like element that can make tutorials accessible to more people without inflating the content itself.

I'm still incredibly annoyed how constrained our web knowledge is to the feature set of ancient paper technology. We can click, hover, collapse areas, play videos and react to user actions yet most content is just these lazy walls of text. Event OP here uses footnotes that just scroll to the bottom of the page adding very expensive context switch for the reader rather than take advantage of the web browser capabilities like hover or modal pop ups.

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

#145

Post by mike_hearn »

kepeko wrote: post #128

That was a good bit of humor. Also there are some popular ways of explaining things that don't do the job (your experience is maybe different). For example: try to learn very basics of object oriented programming. The tutorial will inevitably have examples like "Class Bicycle" or "Class Car". These are out of programming context and never helped me to understand how to benefit from OOP in programming. Another example…

Class Car isn't a bad place to start. It's a real example and something you will find in professional game engines:

https://dev.epicgames.com/documentation/en-us/unreal-engine/...

A lot of kids who learn programming are motivated by a desire to make video games, and everyone already knows what a car is, so such class hierarchies are a good way to teach the concept.

On HN it's trendy to bash OOP and inheritance but it's a bubble; contempt born of familiarity. Real world codebases all use it extensively, including new codebases, and they use it because it's often a reasonable point in the design space for modeling problems. It's not perfect but the alternatives all have major issues of their own.

Obviously once a budding developer realizes that he can't find a job writing game engines and 'graduates' to writing DB driven web apps, the objects and class hierarchies he finds will be representing much more abstract concepts. But by then he'll understand what those concepts are, having mastered them in a less abstract concept space.

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

#147

Post by jaapz »

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…

This is basically the user testing approach as described in "Don't make me think" by Steve Krug. You can use it to test usability of your applications as well.

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

#148

Post by bocytron »

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…

The site that got me into programming as a teenager was called "FromZero" and explained how to write programs in C for non-developpers. From installing the IDE, to how to open the console, it carefully explained each step, sometimes saying "don't worry about Snarfus, we'll get into that later". It was amazing, and I owe this website my career.

That being said, I agree writing doc is time consuming and it might not be your priority, in this case partial docs is better than no docs at all. But if your target is beginner developpers, imo you should consider them as non-developpers, as you correctly descibed them.

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

#149

Post by roelschroeven »

f33d5173 wrote: post #87
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…

It says "me, a beginner " The hn submitter presumably edited for length

By changing "non-developer" to "developer" (moving "beginner" from the end to the beginning doesn't really change the length). That's quite an intrusive change, it seems to me.

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

#150

Post by timwis »

One minor tip that I think can have a big impact: whenever writing down something to run on the command line (e.g. for documentation or other kind of sharing), always use the --full-version of the flags (instead of the short -f version). The extra information it conveys is worth a lot. If someone gets tired of typing it, it's easy to find the short version.
Post reply on HN