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

421–430 of 455 posts

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

#421

Post by ryzvonusef »

Reminds me of an acronym that defines this sort of behaviour: COIK.

What is COIK? well everyone knows what COIK is, no need to bother explaining.

COIK is 'Clear Only If Known.' Did you really have to ask me about such a simple thing? Now run along.

____

There is so much assumed knowledge that writing guides becomes a matter of how simple you have to go, before you start insulting the reader's intelligence. (A computer is a magic box that goes DING!)

If you writing a guide, do you explain what a terminal is and where to find it? Or do you presume they know what it is and start sharing command lines? Is setting a minimum knowledge bar acceptable or are you showing your bias?

____

Obligatory XKCD:

https://xkcd.com/2501/

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

#422

Post by stuaxo »

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.

I want a linter against this. I have a hatred for those kinds of docs, they take up screen space, its worse than nothing.

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

#423

Post by luxcem »

peteforde wrote: post #45

I find that a lot of project homepages (or GitHub README.md these days) are riding high on "if you're reading this, you already know what this is for" energy. What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool…

What I really really want to read in a README is *why* did you build this? The "rationale" section of a README is almost always the most interesting part.

I can read the code, I can understand how it works but I cannot know why you decided to tackle this issue a certain way.

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

#424

Post by account42 »

whatevaa wrote: post #410
godelski wrote: post #389

Earlier quoted context omitted.

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 toda…

In code documentation doesn't support such thing. And documentation outside of code suffers from rot.

We are talking about MSDN not some source files. Even if those pages are generated from in-code documentation that generation step can use whatever transclusion mechanisms Microsoft wants to add.

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

#425

Post by account42 »

godelski wrote: post #391
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…

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…

This kind of bad documentation is actually way more common in teams that require doc comments for all code, which are then promptly auto-generated by the IDE and never filled with actually useful information.

Self documenting code in this case would mean using a type that encodes the unit - which would have the additional benefit that the compiler or other tools can now check correct usage.

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

#426

Post by account42 »

tetha wrote: post #381
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…

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.

Better yet would be unit-aware types. Then instead of

duration_ms = 1000

you can have

duration = 1s // or duration = Seconds(1) in deficient languages

and it's either a compile error or the type system enforces the correct conversion.

As for the bad rap of hungarian notation, it's mostly from people using it to encode something that is already clear from the types. "fDuration" helps no one over just "duration".

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

#427

Post by account42 »

fingerlocks wrote: post #366
shakna wrote: post #306

Earlier quoted context omitted.

struct AVMetadataKeySpace - a unique unit representing each of the metadata key spaces supported by AVFoundation.

? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me. There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.

> It’s used to query collections of keys grouped by the KeySpace categories

Sounds like something that should be mentioned in the opening sentence of https://developer.apple.com/documentation/avfoundation/avmet...

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

#428

Post by account42 »

alt227 wrote: post #356
peterfirefly wrote: post #350

Earlier quoted context omitted.

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

But I would bet that those variable labels are never translated into other languages.

Presumably those enums are used to select localized labels and you need all these cases to cover unique words / phrases that exist in the supported languages for specific familiar relations.

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

#429

Post by account42 »

wang_li wrote: post #343
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.

The issue here is that people are treating reference materials as tutorials intended to cover your exact concern at the moment. You are expected to know what a narg is and what flargling means. In more real terms, the documentation for screen savers https://developer.apple.com/documentation/screensaver?langua... won't explain what a view is, what subclassing is, or what a Rect is. Those are required knowledge to cons…

No, you missed the point. The problem isn't "narg" or "flargling" - those are just random stand-ins for normal words. Instead the problem is that the description says nothing that isn't already said by the symbol name. Whether or now you know what "narg" and "flargling" mean, a documentation page for Nargflargler that just describes it as "Flargles the narg" provides zero additional information to you.

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

#430

Post by fingerlocks »

shakna wrote: post #419
fingerlocks wrote: post #366

Earlier quoted context omitted.

? Did you read the link? It’s used to query collections of keys grouped by the KeySpace categories, instead of a single item per key. Makes sense to me. There’s plenty of other poorly documented Apple APIs (io_surface), but this isn’t one of them.

The struct is only named on the link you provided, not documented. So thanks for showing the absolute irony of it not being greatly documented, allowing people to misinterpret what it means.

Because it’s a boring enum in C, auto translated to a swift struct.

And if you’re reading the documentation because you do development, then you would already know that the header files are installed on your computer and you can trivially verify that there is nothing to document because it’s just a query key.

Post reply on HN