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

411–420 of 455 posts

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

#411

Post by devjab »

mike_hearn wrote: post #141
devjab wrote: post #80

Earlier quoted context omitted.

> Had to explain to him public, private, internal, and also static the other night. Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to se…

Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean. Static methods are useful for namespacing, e.g. var instance = SomeThing.fromString("...") In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't…

I probably shouldn't have worded it quite the way I did. Considering I praise Go's access modifiers. What I meant was the "old" way of having lots of them and explicitly having to write them out. I haven't tried Kotlin but it sounds nice.

What I like about Go is the simplicity. Everything inside a folder is a package/module and any method beginning with a capital letter is public while every method starting with a lowercase name is package/module only. Coming from a decade of C# it was such a nice thing.

I do work with a lot of Python where you don't have private methods. I mean, you can set up your corporate environment to "hide" _methods or whatever, but they are never turly private, and static methods are... well... they are basically just namedspaced top level functions.

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

#412

Post by zestyping »

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…

Code can show you HOW something is done. Only documentation can explain WHY it is done that way.

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

#413

Post by jibal »

annienotadev wrote: post #406
jibal wrote: 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).

Good observation. Silly is the point. You nailed it.

So your point is to be silly (what you call "good clean fun"), not to offer a valid criticism or to be in any way helpful--yes, I nailed it.

> I really appreciate the folks who take time to share their knowledge and write up tutorials and give tips and so on.

One wouldn't know it. Many here are foolishly taking this as a valid criticism of those folks.

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

#414

Post by jibal »

annienotadev wrote: post #405
Dementor430 wrote: post #386

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

OPs everything is flawed but she tries really hard.

If this is you trying really hard ...

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

#415

Post by turtleyacht »

efitz wrote: post #190
aDyslecticCrow wrote: post #181

Earlier quoted context omitted.

Or let the Junior rewrite the docs while they're scratching their head, and push an update once they've figured it out.

Wow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”

They're not necessarily prohibited from asking questions if they're stuck, though. But also search in the chat channels for similar issues.

Updating docs in source control also onboards folks to code review. It would be weird to update docs and get a hostile reception.

While nice to walk through with someone and conduct a usability study, just leave it better for the next person (who could be yourself, if you forget). That has happened before.

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

#417

Post by jibal »

dizhn wrote: post #258

Pretty low effort as blog posts go.

Apparently it was so much more effort than she was willing to expend that she ended up just randomly banging on the keyboard ... and yet many here are treating this as some sort of serious criticism.

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

#418

Post by turtleyacht »

Unfortunately, the curse continues: follow up with how the text gradually coalesces as understanding grows. Realize how much easier it is after completion. Forget what "don't know what one doesn't know" felt like.

At least the beginner perspective captured enthusiasm, empathy (an alternative error condition for a path to a hidden file), and the request for feedback.

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

#419

Post by shakna »

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.

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.

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

#420

Post by rmunn »

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.

Some varieties of in-code documentation do support links, e.g. XmlDoc which is the de facto standard for documenting C# code (and therefore the most relevant to my comments about MSDN because I was referring specifially to the .NET API documentation) has multiple ways of embedding links in your in-code documentation comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...

MSDN even uses those, a lot. But not enough. I wish that every time they had a "Foo(string parameter) - uses the default FooOptions" it was a link to the documentation section where the default FooOptions are listed. But usually you're left to find the default FooOptions yourself, which means 5-10 minutes of digging through docs (1-2 minutes if you're lucky) that I could have spent writing or reviewing code instead. That adds up.

Post reply on HN