Live data from Hacker News

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

anniemueller.com

391–400 of 455 posts

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

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

Related to this is the omitting of units. I encountered something like this in the Android SDK (years ago, dunno if it’s still like this). setFontSize(float): sets the font size. Cool. Sets the font size in what? Points? Pixels? Device-independent pixels? Which of the 12 different types of measurement Android supports is used here? I can’t remember exactly what it turned out to be, but I know it wasn’t the unit I exp…

This is why I rage against the crowd that promotes "self documenting code". There's no such thing, even if you should strive to make your code as readable as possible. But if there's a way to misinterpret it then you can bet many people will.

The biggest problem is that this ends up creating so much extra work. An extra 2 seconds from the dev could save hundreds or even thousands of people hours of work. I can't tell you how many hours I've spent chasing stupid shit like your example. I don't know a single programmer who hasn't.

I just don't understand why everyone's frustration with documentation (or lack of) doesn't make obvious the importance of good documentation. Every single one of us has experienced the wasted time and effort that results from the lack of documentation or from low quality docs. Every single one of us has also reaped the benefits of good documentation and seen how much faster it makes us. How does anyone end up convincing themselves that documentation is a waste of time? It feels insane

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

#392

I call it "Kindergarten speak". People at the highest level of technical expertise sometimes have it, where they can patiently, and in understandable terms, explain to the most junior (but interested) party so the stuff sticks. Others, while extremely nice and helpful, just don't "get" that their advanced jargon or, in my workplace, advanced mathematical language/notation, however elegant for themselves, is a huge hi…

This is obvious for us who believe in and spend time on writing good documentation, but there are a surprising amount of devs out there who don't. "The code speaks for itself" people. Never understood them (literally) it's like some cult from the middle ages.

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

#393
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…

  > They’re more like academic papers (peer-to-peer communication of new discoveries)
This made me laugh because I frequently see HN comments on arxiv papers claiming things like the authors are trying to show off with their math rather than the math just being an effective communication tool. Honestly, if anything, papers are written to too broad of an audience and we get these 10 page papers that could be communicated in 3. I'm unsure if this has been a good change. (Yes, I read the whole comment)

Just because you have access to the text doesn't mean you're the intended audience.

Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one

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

#394
post #255

Earlier quoted context omitted.

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

Correction: They are very good at writing seemingly-good explanations. The explanations may or may not be correct.

Correction: They are quite good for this: Easy beginner level stuff. For that specific thing, they are much MORE correct than they are wrong.

The status quo is a moving target. 6 months ago what you said would be fully correct. This is no longer the case, now you are only sometimes right and mostly wrong. It is getting better.

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

#395

Earlier quoted context omitted.

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

[flagged]

Don't like your tone. Please speak in a non offensive way or leave.

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

#396
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…

> If not, note every single place they fail, address each one, and repeat with a new user.

Might not this loop be invoking Goodhart's Law?

What is "address each one": are we just changing that document, or are we (also) changing something in the system that the document is about?

If no newbie has any problem following the document, is that still a good document for non-newbies?

If no newbie has any problem with the system that the document is about, are there any downsides?

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

#397
post #225
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.

[deleted]

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

#398
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…

are you interested in giving a talk/presentation about this

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

#399
post #90

This level of extreme hyperbole is silly and not in any way helpful. Try analyzing an actual tutorial (which will only be an analysis of that one--quality varies a lot).

That was the analysis of an actual tutorial.

Oh? Which one?

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

#400
Just confirming, I've seen that the title between the post and link are inconsistent incase there's any confusion.

While I agree, the difference is significant, and it is often the case that a a decent tutorial/blog post on a technology is rarely tailored to non developers

I do think there's a kernel of truth in this for with educational content written by developers. I think many developers underestimate the attention and care that's necessary to write high quality education material. Not to say they shouldn't, it's a valuable skill for everyone to develop but it doesn't always come naturally.

I think one part of it is, in writing the content sometimes someone who is inexperienced in writing, might be writing something with dual roles in mind. They may be venting their frustrations with learning the technology, selling their experience and accomplishments (to any potential employers who may be reading it, which is where some name dropping might be coming in) and using the format of a tutorial as a vehicle to do so. They may also just not have a clear objective of what they want to write in mind and they just want to share some information and they initially wrote a tutorial and veered off on to something else.

If you're someone who is reading something like this, it can actually be annoying or confusing if you went into the tutorial expecting one thing which doesn't end up being there. For a beginner even more so, as you lack the domain knowledge to know if you need to disregard these tangents or skip forward, if you're more experience it feel like someone is wasting your time by telling you they were going to explain X Y Z then it ends up being some rant passing as a half baked tutorial. That said I rather this than AI slop, but reading it can be equally annoying if it feels like the author doesn't respect your time in the way AI slop feels like there's an expectation your time reading it is worth less than the time the author would spent writing it.

The issue here for the reader is usually the content is inconsistent with their expectations, and for the author they possible communicated that poorly.

Yes if the author has mistakenly assumed an article not written for them were written for them, well yes that's on the author. But taking what they say at face value or even the title used at the post I think there is a point of value to take away from this for those writing anything ranging from education material to a post mortem.

Know your objective, the key information your communicating, has the way you've written effectively communicated that to your intended audience? Cull things that detract from this. And of course there's nothing wrong with unstructured forms of writing, they can be really fun, but they are the last thing someone wants to read when they are in the middle of trying to fix a technical issue they don't entirely understand. That can largely be avoided by with a better title, or avoiding insinuating the post is something it's not.

Post reply on HN