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

381–390 of 455 posts

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

#381

Post by tetha »

Aaargh20318 wrote: post #241
imgabe wrote: 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'm sad that hungarian notation has gained into such a bad reputation. Sure, you can overdo it, but a `duration_ms` or a `response.size_bytes` or a `max_memory_mb`, or an `overhead_ns` is so much easier to use.

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

#382

Post by marklubi »

sfn42 wrote: post #377
marklubi wrote: post #354

Earlier quoted context omitted.

Thanks for taking the time to respond. Ultimately though, most of those aren't required from the beginning, but the syntactic sugar, abstractions, and performance gains from them are amazing. You probably already know, but I'll opine a little bit about extension methods. I use them a lot. Entities > Repositories > Functionality. All split out. - Entities (pretty much just gets and sets, nothing more than necessary).…

Would you happen to have something like a github repo with examples of those repositories? I'd be interested in seeing that. Personally I'm not a big fan of copious extensions. I use them some times but I'd describe my usage as sparingly.

I wish. It's on Github, but my hands are tied and I can't share them since it's someone else's property now (hooray for exits, I think).

It's mostly a thought process...

I have or need something (entity), lets get data about it (repository/extensions), we need to do something with this now (only extensions).

Lots of "static" and "this" involved, but the separation and eventual simplicity makes it worth the effort.

Edit: I tried going through some of them to anonymize some for examples, but it felt like treading in dangerous territory.

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

#383

Post by billforsternz »

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.

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

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

#384

Post by xnx »

angiolillo wrote: post #368
zahlman wrote: post #359

Earlier quoted context omitted.

I mean, if the test user can't figure it out at all, how is the rest of the UI/documentation supposed to get evaluated?

Great question! If you let someone flounder on one task indefinitely then you don't learn anything about subsequent tasks. But if you correct them too quickly you won't uncover the other approaches they would have tried to complete the task. Most research plans define cutoffs such as: 1. Participant expresses extreme frustration or gives up 2. A couple minutes have elapsed from the first failed attempt 3. Participant…

Exactly. You want to learn as much as possible from each study. Explaining too soon reduces amount learned, as does ending the study early because a small hint wasn't provided to get to the next step.

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

#385

Post by Biganon »

vhantz wrote: post #176
Biganon wrote: post #162

Earlier quoted context omitted.

Site du Zéro mentioned! I always assumed it meant "a website for 'zeros'" as in "complete noobs"

I owe so much to that website. I first had access to a computer at 13, some nights of the week and only some of those nights did I also have internet access. Somehow I still discovered le Site du Zéro at that time. While I barely touched a computer the year before, I still was able to go through the whole C++ class and learned most of the basic things and reflexes I've ever needed to work in software development. Tha…

SDZ should have been Heaven for me, but even as a teenager, I just couldn't get past the omnipresent enthousiasm and the smileys at the end of each sentence :)

:)

Guess I've always been grumpy.

Oh and yeah it's probably been enshittified nowadays, everything has. Wouldn't surprise me if they partnered with Ecole 42 to inundate the job market with programmers without degrees and drive the salaries down even more.

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

#386

Post by Dementor430 »

OPs argument is flawed. Documentation is not there to teach you from scratch. Its there to describe a projects intended behaviour under normal conditions. Often times people will cry about lacking context and expect you to basically use it for them. I would heavily recommend against that as you will end up as unpayed and burned out tech support...

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

#387

Post by GarnetFloride »

Right now I am a tech writer and the curse of knowledge is hard to break for many people. I've gotten a lot of docs from devs that are obviously just reminders for themselves of what they already know. I've had to flesh out docs that just stop halfway through a procedure.

Please just admit that writing docs is hard. Because it is. Just because there is a lot of writing going on in college doesn't mean you learn how to do technical writing, academic writing is very different.

Go to the support team and ask them what questions are they sick to death of having to deal with (hint: its usually something you would think is pretty easy) and rewrite the doc to handle it. Then watch what happens to the support questions, if that disappears you did it right.

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

#388

Post by astrange »

billforsternz wrote: post #383
imgabe wrote: 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.

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

The more useful answer is:

a) it needs namespaces

b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional.

c) so instead two letters means a system framework and three letters means a user framework

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

#389

Post by godelski »

zahlman wrote: post #355
rmunn wrote: post #288

Earlier quoted context omitted.

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…

> 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. It's better for maintenance (of the documentation) if the default options are only described in one place. (If the defaults change in a new version, this ensures the documentation doesn't h…

This is only a problem if you write it twice. Instead you can write it once and display it twice.

Hell, I even do this on my github.io website that uses markdown. You can just write some text in one document and read it in another.

We're programmers, so we should be lazy. It's about being the right lazy. You can be lazy by putting of a task today that takes more effort tomorrow or you can be lazy by doing a task today that takes less work than it would take to do tomorrow. Most people choose the former and wonder why they have so much work. In programming if you're doing redundant work then you're probably being the first type of lazy

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

#390

Post by billforsternz »

astrange wrote: post #388
billforsternz wrote: post #383

Earlier quoted context omitted.

One problem I remember from (briefly, fortunately) dealing with Apple APIs is wondering incessantly why every API (I was looking at) started with NS. Admittedly these days any AI would tell me it stands for Next Step. But if you are creating a new thing with a quirk like this please explain it once, in a place that's easy for the student to find.

The more useful answer is: a) it needs namespaces b) but giving people namespaces is unironically bad because it's what lead to "enterprise development" style APIs like C# where everything is named System.DataStructures.Collections.Arrays.Lists.ArrayList, as if giving something a longer name makes it more professional. c) so instead two letters means a system framework and three letters means a user framework

I quite like a terse but consistent conventions myself. I remember finally being able to quiet the tedious part of my brain that couldn't get past the NS conundrum when I finally came up with the NextStep thing as a reasonable theory.

In other words, my only complaint is that this Apple convention is not more easily discoverable. Or perhaps that the expert author of the book I was reading (this was back in the day) didn't feel the need to share it with his readers.

Post reply on HN