441–450 of 455 posts
Earlier quoted context omitted.
Wow, way to double down on “I really hate everyone who doesn’t have exactly my skill set and experience.”
I'm ... confused what you mean. If the junior is gonna untangle the docs anyway, why not make them directly update the parts that confused them once they're through it.
Earlier quoted context omitted.
Great job, you've failed to document the point.
Regardless of the level a tutorial is given at, there is information that is missing. A well written tutorial knows its audience and contains all the information for that audience. Sure, I will grant that someone who doesn't know what a computer is shouldn't be expected to follow a tutorial to install PostgreSQL on a headless linux server with proper security protocols in place. The issue is more that it's extremely…
What information was missing?
> and fail to describe what it is the user actually has to do.
How is "go to a folder and copy file content" is not such a description?
> doesn't necessarily mean you have the domain knowledge necessary to make leaps that are frequently present in tutorials.
Again, rather than speaking generically, how does this post demonstrate it? What leap is present in "this tutorial" that an average reader would not have the knowledge to make?
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…
Not in general, but here it could be called:
setFontSize (dvi_pixel_t size);Earlier quoted context omitted.
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".
Earlier quoted context omitted.
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) d…
Earlier quoted context omitted.
I worked with someone who was great with this. They’d go through the docs and do exactly what was said, document where problems were hit and then repeat from scratch again and again. Seemed slow but their docs were excellent and I’m sure it saved more time having him hit each thing once than everyone else hitting them loads.
Funny enough, we had a hell of a time running a helpdesk where we designed the docs -- many of which I wrote myself -- to be executed exactly as written . Guess what humans hate to do? Especially the smart ones, which of course you want to employ on your helpdesk? They just would not read the damned instructions. I think this was because many of the instructions were dumb. We were explaining decades-old bank stuff. I…
Earlier quoted context omitted.
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 lo…
Earlier quoted context omitted.
> Beginners have to be nurtured through lots of context that builds up slowly. My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night. I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.
> 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…
> doesn't require you to have object instances to call non-static functions
Not sure, what you mean, because you need to pass something for self?
Either:
obj.foo (args...);
cls.foo (obj, args...);Earlier quoted context omitted.
"Most tutorials are not for non-developers" That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers. Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, t…
> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps See I missed that context :D Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead. If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really goo…
This is how I, a web developer, feel whenever I'm required to build something using cmake. I guess I need to go read a book about it or something because the instructions seem different every time.
The main advantage of cmake is it's slightly easier to use than autoconf so long as you stick to the path. Do not attempt to leave the path. Also the path is poorly signposted.