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

371–380 of 455 posts

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

#371

Post by peterfirefly »

delecti wrote: post #369
peterfirefly wrote: post #350

Earlier quoted context omitted.

There are indeed languages that don't have the word "cousin" -- or "uncle" or "aunt".

And conversely, there are languages with different words for "father's sister" and "mother's sister", and for male vs female cousins, etc.

And we don't even have to get exotic for that. My language, Danish, is just a run-of-the-mill Germanic language and those terms are "faster", "moster", "fætter", and "kusine".

Some of the East Asian languages are crazy regarding terms for family members. It's like learning foreign words for plants: I just give up. I will not even attempt to learn them.

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

#372

Post by mihaaly »

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 am stuck in an organization for some personal reasons.

The first thing I noticed when I joined was the culture of "Please ask when something is not clear". After was given a quick overview in person.

You guess: almost everything is unclear. A mess. Need to ask a lot. Task descriptions, purpose, reasons, whys, wheres, what does this comment mean, why are these things contradict each other, and so on, and so on.

And except asking KG, usually the answer is: ask XY. Or KG.

People always busy, always in rush, give a condensed answer raising the same amount of new questions that it answers.

When KG is out, productivity slows down.

And all this beyond the usual in a meeting, out with customer, on holiday, sick, the children is sick, held up in a traffic jam, car broke down, need to finish project P so schedule something for next week, and all those kinds of common things making the relevant person unavailable when "something is not clear".

And beyond the forgetting 4 things of the 15 new info given by the time we are finished with the converstaion. No written trail to look back at.

When 3 person paint a complete picture then all above happen three times in a row, or in a never ending loop.

Productivity suffers, quality suffers, I will leave as soon as I can.

Positive things? Probably that the expectations are low. And they pay well. And by now I am irreplecable in a local subset I was hacking together (I do not call it work or development), not even KG can help others there! I will leave on my own terms (as usual, unluckily).

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

#373

Post by raydev »

rmunn wrote: post #288
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.

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…

In some fairness, the page existing at all is half the battle. I'm glad the canvas exists for the paint to eventually, maybe, one day arrive.

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

#374

Post by prewett »

psunavy03 wrote: post #357
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…

And then there is Microsoft's annoying habit of creating APIs which return the information you actually need . . . nested three levels deep inside a bunch of their own custom data structures. I've basically resigned myself to "it makes sense in Redmond somehow, even if it makes no sense to me."

Microsoft's APIs basically shove all the implementation details onto the API user. This is, of course, abysmal API design, but "tasteful design" (in any sense) and "Microsoft" have never been in the same building. But it does make sense. And it also tells you how to interact with Microsoft APIs: the same way you interact with the hardware details that assembly languages export to the user, namely through a wrapper. (But, taste is difficult to find; that wrapper might have imbibed some Microsoft "design" by virtue of being exposed to too much Microsoft.)

Rant: if you want antialiased text, you need to use Direct2D. Direct2D is one of those APIs that waste developer's lives. You have to allocate your own framebuffer, for crying out loud. And then, you have to reallocate it if it ever disappears for some reason, and the docs don't tell you when this might happen (hot swap a video card? change monitor resolution? User moves window to a monitor with a different video card?).

I found this out developing a cross-platform UI library, https://github.com/eightbrains/uitk, leading to my above conclusion that the only proper way to relate to the Microsoft API is through some layer.

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

#375

Post by tartoran »

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…

But that could be linked up rather than have you fumble through to find them.

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

#376

Post by clickety_clack »

CaptainOfCoit wrote: post #325
Aaargh20318 wrote: post #241

Earlier quoted context omitted.

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…

That's more about API design than about documentation though, as with a proper function name/using value objects/something else, you already know what the correct value to pass is. It's a widespread issue though, where the API designer doesn't clearly communicate either what the thing does and/or what the thing needs.

If you don't need the docs then you don't need them, but sometimes we all need a "hey bro, I know you're a little lost so I'm going to break down what's happening in plain English". At a certain point you just don't have the entire code base in your head all the time and you need a reminder on what exactly the Flargle team does to all the Nargs.

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

#377

Post by sfn42 »

marklubi wrote: post #354
sfn42 wrote: post #336

Earlier quoted context omitted.

I agree, C# is my language of choice and I've been using it professionally for over 5 years. I use it for personal projects as well. I'm referring to all the stuff C# has that Java doesn't. Async, ref/in/out keywords, extension methods, linq, lots of stuff. Maybe it's not a big deal, like I said I wouldn't really mind it. I just think Java is a bit simpler in this regard which is an advantage for beginners. Some diff…

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.

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

#378

Post by karaterobot »

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…

I guess I disagree that it's a good thing.

As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers.

There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think.

I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else.

The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.

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

#379

Post by ArcHound »

taink wrote: post #304
ArcHound wrote: post #174

Earlier quoted context omitted.

Hello, I am just now trying to upgrade my blog. Can you please point me to sites that do this right?

An extreme example would be gwern.net -- specifically you might want to read https://gwern.net/about and https://gwern.net/design

Thank you. That is indeed quite extreme - I could use an article progress bar, footnote pop-ups (maybe, link back into article might be enough). Definitely not doing my own window manager. I'll try and read the rest of the design page with fresh eyes, maybe I'll learn something else.

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

#380

Post by testing22321 »

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.

Triangle theTriangle = new Triangle()

Lives rent free in my brain.

Post reply on HN