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

281–290 of 455 posts

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

#281

Post by pakitan »

joenot443 wrote: post #219
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…

This is an important clarification. Checking out the homepage, Annie says her job is "content & documentation things", but also mentions CSS as a hobby, so I think it's a safe assumption this is the "non-professional hobby developer" niche which I think we'll see continue to grow. It's a hard balance to get right. I've seen "install this tool" sort of tutorials which literally introduce the concept of opening a termi…

> It's a hard balance to get right

Not really. With the wide availability of AI, you can dumb down almost any text to any any level you want.

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

#282

Post by multifasciatus »

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.

AVMetadataKeySpace

A structure that defines a metadata key space.

source: https://developer.apple.com/documentation/avfoundation/avmet...

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

#283

Post by philipwhiuk »

> Just for shits and giggles, you can de-sham the chronostatiomatrix by running —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] but that’s optional.

Except in most real cases you're following the tutorial for, where it is both mandatory and non-obvious it's not been done.

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

#284

Post by angiolillo »

mschuster91 wrote: post #253
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…

> 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 target audience then the rest of the test may not be valid anyway.

Otherwise, there is utility in forcing yourself to watch your users struggle with your product. The best product developers/owners I know have a bottomless appetite for observing people use their product, even if doing so means deferring the rest of their "full backlog of shit". Perhaps they're less efficient in the short term at churning out lines of code, but the understanding and empathy they develop makes them significantly more effective in the long term.

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

#285

Post by whstl »

a96 wrote: post #126
whstl wrote: post #40

Earlier quoted context omitted.

I've been coding in C++ since the 90s, that's also how I feel whenever I'm required to build something using cmake.

Which is funny, because it's probably the easiest to use (common) build system around.

I beg to differ. It's only easy for projects you're constantly using daily. People tend to build all sorts of abominations with it.

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

#286

Post by philipwhiuk »

marklubi wrote: post #43
Swizec wrote: post #4

Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience. And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago. This is w…

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

Maybe he and his teacher are caught in a loop ;)

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

#287

Post by ranger207 »

marklubi wrote: post #89
bckr wrote: post #82

Earlier quoted context omitted.

He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.

I fully disagree with Java as a starting point and it was an interesting conversation with the teacher. Apparently, "College Prep" courses more or less determine that Java is the language that they should use. His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though. He was apparently the only person in the class that said he wanted to…

Java's a pretty good beginning programming language. Outside of the mystical incantation of `public static void main(String[] args) {` and what the difference between `new ArrayList` and `ArrayList.new()` is (I still don't know but I haven't really touched it since college), it's a good statically typed imperative language that you can throw objects and functional stuff into when it's time, isn't going to give you weird errors about indentation, has just enough pointers for you to learn how to avoid a `NullPointerException`, does things pretty "conventionally" (ie, there's not a lot in Java that doesn't also show up in other languages), and is easy to compile and run (when you're not using 3rd party libraries, which students in something like a Data Structures and Algorithms class aren't going to be using). Ideally you have another class teaching you another language too so you get the double bonus of learning what a language is and what a language isn't, and Python's good for that, but by itself Java's fine

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

#288

Post by rmunn »

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.

This is just one example of how metrics can distort things, of course. Someone in management said "We want 100% documentation coverage of every method," so the staff dutifully wasted everyone's time by writing "setDefaultOptions: sets the default options". It's the kind of thing an LLM could have done better, and if you know my opinion of LLM's, you'll know that's damning with faint praise.

My own bete noire here is MSDN. It's full of overloads like "Foo(string parameter, FooOptions options) - actually useful documentation. Foo(string parameter) - does Foo with default options." But to find out what the default options actually are, you have to find another page, probably the FooOptions constructor. I wanted the default options to be mentioned on the "Foo(string parameter)" page, and they so rarely are. (A few pages are better, thankfully).

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

#289

Post by skydhash »

FranzFerdiNaN wrote: post #260
skydhash wrote: post #189

Earlier quoted context omitted.

Also a lot of beginners skipped a lot of (cultural?) foundational knowledge. A basic understanding of filesystem, network, and os commands would go a long way for communication efficiency. Instead, they’re cargo-culting.

There really is a huge gap between a programmer and being capable at using a computer. I work in the data space and while im good enough for my own needs with Python and grew up in the 90s with MS-DOS and Windows 3.1/95, the second i have to use something that is build by and for programmers i too end up feeling like the blog post describes.

The difference is merely how this thing works vs how this thing is used. And the glue factor between the two is ops.

Between the developer and the user, there should be the maintainer role. Someone that took a software and make it run on a specific system. That requires familiarity with the system internal and build systems.

This is why packages managers like in linux distributions are a great solution. A working solution is often just a command away. App stores could be good too, if not for the gatekeeping effects.

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

#290

Post by magic_hamster »

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 content for the Shoobahooba Snarfus ecosystem beyond some 'get started' guides.

Post reply on HN