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

131–140 of 455 posts

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

#131

Post by noufalibrahim »

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.

I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through.

I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.

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

#132

Post by a96 »

protocolture wrote: post #56

Most docs I read have their prerequisites spelled out. This is the version of this OS with this plugin that this guide is written for. So when I find that, inevitably, something has moved, I can figure out how my setup differs and search for the difference. If you cant stand up the prerequisites, then the doco isnt for you, you should be searching for documentation on how to stand up the prerequisites.

Funnily that's one of the first questions on my mind when I look at a new program or library. What was it written in or what platform for, what's the build system or requirements and what does it actually do. Quite often I decide to avoid a thing entirely when I can't figure this out after reading the main documents. Sometimes you can look at the repo tree and just know, but often not.

This should be the first sentence in the landing page or README IMO. Instead you get something that looks like marketing copy written by LLM fed on BS generator output. Many projects just seem to refuse to tell the prerequisites at all.

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

#133

Post by constantcrying »

Why be so snarky? Documentation is there for users, it should assume that the user has the necessary background. If the user doesn't it is his responsibility to read up on the relevant background.

Pushing the burden of education on every single developer writing a tutorial is absurd. It makes the documentation unreadable to the people who need it the most and wastes time and effort. This style of documentation is totally fine.

Education is your own responsibility, do not push it on others.

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

#134

Post by scott_w »

Honestly, I'd say this doesn't even just apply to beginners to software development. It's applicable to even experienced developers who are new to a language or concept.

I've been teaching myself Rust in the past week and I've definitely noticed that, when I hit an error, a lot of library documentation assumes more depth of knowledge than I have right now. Say I want to know how to use a specific function and, beyond the quickstart, the docs are just a reference that keeps talking about Traits. I'm sure it'll click eventually, but right now, I just need to know how to call the function and fix the error I have!

Side note: I've rediscovered why Stack Overflow is so helpful as some of the answers there have helped me understand what's happening with different issues I run into!

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

#136

Post by creesch »

I am surprised nobody mentioned the curse of knowledge: https://en.wikipedia.org/wiki/Curse_of_knowledge

It is actually a fairly well known phenomenon, certainly in educational circles. Being aware of it when you are writing any form of documentation is a first step. But even then, it is very difficult to properly assess the knowledge entry level of your audience.

Having others read through your documentation and importantly work with your documentation is a good strategy.

One thing I can also highly recommend is simply start out with a list of assumed prerequisite knowledge in your intro. Specifically things like certain environments, frameworks, etc. Bonus points for not only listing those but also linking to the documentation for those.

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

#137

Post by mike_hearn »

JohnKemeny wrote: post #120
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.

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.

Java doesn't have an internal modifier. Concepts like public, private and static exist in Python too.

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

#138

Post by maxloh »

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 think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field.

In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.

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

#139

Post by [deleted] »

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…

[deleted]

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

#140

Post by jiggawatts »

csallen wrote: post #30

Most technical writers (and communicators in general) have an insufficient appreciation for the curse of knowledge. This takes me back to running a World of WarCraft guild as a teenager. We would organize "raids" maybe 3 to 4 times a week. It involved getting 40 of our guild members from all over the world to sign on at the same time, and spend hours facing off against dragons and other monsters inside dungeons. It w…

I keep saying that anyone who could run a 40-person WoW raid is almost certainly going to be a top-tier project manager.

Those raids are like herding cats. Distracted, teenage cats with connectivity issues.

Post reply on HN