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

211–220 of 455 posts

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

#211

Post by simultsop »

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…

Without AI, it was really hard to get to understand some docs. Today if you don't use AI for these situations shrugs

Most cases it is not that docs author forgot users wont have same toolchains. Simply do not bother reducing config files to share just source code. Indirectly pushing users to make use of same tools.

Hopefully in 20 years no one will be going to check the source code of anything, and programming is elevated even more.

50 years is crazy amount of time, to stay this primitive. Tech shouldn't just evolve for end users.

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

#213

Post by wonger_ »

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 demographic. But HN took it in a different direction, which is fine.

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

#214

Post by econ »

What it should look like:

Have a bunch of checkboxes at the top, one for each buzzword, each technology and all other things a 12 year old wouldn't be familiar with.

You check which you think to be familiar with and all other things unfold a short description with links to similar interactive documents.

Each section comes with 1-5 star rating for how well the reader understood your explanation.

Then you gather the data as the subjects suffer though the tutorial.

If people come from specific backgrounds further tailor the explanation for them.(Like babazoofoo for C++ developers.)

Let there be a browser extension or an API that checks (and hides) the familiar boxes for you.

I didn't say it was possible to make. It would be glorious to have. If you know all the tech involved the whole thing implodes into a one line code example.

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

#216

Post by wonger_ »

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…

My first programming class was Java. That was 8 years ago. Maybe the curriculum designers thought Java would be relevant for the workplace? The education system always lags several years behind industry trends.

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

#217

Post by ajsnigrutin »

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…

Also, it really depends on what the tutorial is about.

There's a difference between a tutorial on how to set up a wordpress on a shared hosting or how to add aditional debugging capability to kernel application core switching routines by patching the linux kernel.

In the first example, "unzip it" might need an additional explanation on how to do it in the command line... in the second,.. well... if you can't even unzip a file without the tutorial, you won't be able to use the software anyway.

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

#218

Post by sfn42 »

throwaway2037 wrote: post #197
JohnKemeny wrote: post #120

Earlier quoted context omitted.

I think Java is dying. If you want to teach algorithmic thinking , teach Python. If you want to teach hardware and low-level systems , teach C.

> I think Java is dying. There are millions of enterprise programmers around the world that use it. If it is dying, then what is replacing it in the enterprise? From my perspective, I don't see any serious competition. At the moment, I see this pattern for mega enterprise: * C++ for scientific, mathematical, financial core libraries * Java for heavyweight backend services that run on Linux * DotNET for thick clients…

Some notes:

.NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good.

NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F tier language. TS brings it up to like C but it's still just not good enough to compete.

I can't see any reason to choose node for typical backend programming and such unless your devs only know JS. Any other language is probably better suited.

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

#219

Post by joenot443 »

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 terminal and pressing Cmd+V and others which expect cron and Make knowledge as very basic table stakes. It's a wide variety!

I think if we're writing for an audience which will contain some amount of beginners or non-developers, it's maybe ~2min of effort to add a little collapsable (straight from Claude if you want) going into what exactly we mean by "cd into ~/.snarfus, creating it if it doesn't exist"

I donno. I remember being 13 trying to install Debian on my dad's old laptop. Any nuggets of knowledge helped.

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

#220

Post by ninetyninenine »

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…

LLMs have mostly eliminated the need for this. They are quite good at explaining things.
Post reply on HN