4 ms·

"RTFM" used to be a valid critique, and it's my immediate response to this article. But maybe I'm wrong. The M keeps getting bigger, and our reading time keep

by kbob 8y ago

"RTFM" used to be a valid critique, and it's my immediate response to this article. But maybe I'm wrong. The M keeps getting bigger, and our reading time keeps getting more fractured. Maybe it's okay to just throw code out without knowing what it does. Or maybe management/engineering culture need to be clear on the external costs of slapdash development and discourage breaking things fast.

DougBTX 8y ago
> Maybe it's okay to just throw code out without knowing what it does. I think at time pressure increases, the grey area between right and wrong grows. Here the hypothetical user did read the fine manual, and they thought they knew what the code did, and when they ran it, the output was what they expected. Really they did everything correctly, except for the fact that they were wrong. This article is addressing the next level up from RTFM. Given a dev that is reading the manual, how can it be optimised such that they can learn to use the tool correctly? How can project standards be defined so that eg, fiddly date formatting code doesn’t need to be repeated?
xtrapolate 8y ago
> "But maybe I'm wrong." I don't think you are wrong. Timing APIs are tricky and complicated. The small print really matters. Experienced engineers will know this, and so the answer in this instance, as annoying as it may be - absolutely RTFM. Also, funky documentation/APIs exist everywhere, unfortunately. Quoting the article: > "You're a new coder, and you find yourself tasked with taking a Unix time_t type value and turning it into some kind of human-readable format" I'd argue that's exactly the kind of mistakes inexperienced coders are prone to make. Hence we have code-reviews.
ygra 8y ago
I think the problem in such situations is that the M needs to address two different use cases: 1. Reference for what exists. This is used by people who don't know what %Ð is a placeholder for. Alphabetic sorting has a big advantage here. 2. Manual for what can be done. This should arguably be grouped differently, e.g. Full dates, years, months, days, etc. since there are often several placeholders for each category that are otherwise pretty far apart at times.
oblio 8y ago
> The M keeps getting bigger, and our reading time keeps getting more fractured. Also the "M"s are generally really, really bad for any practical task. I'd argue that many times they're also bad as references. They're also not indexed or hyperlinked, there's no tables or any smarter form of formatting. I know that there's also the info format but that's rarely used and it's definitely not default, many distros don't even install the tools for it... It's a really thankless job to migrate documentation so nobody's going to do it within our lifetimes, so we're stuck with man for the foreseeable future :(

by kbob 8y ago

DougBTX 8y ago

> Maybe it's okay to just throw code out without knowing what it does. I think at time pressure increases, the grey area between right and wrong grows. Here the hypothetical user did read the fine manual, and they thought they knew what the code did, and when they ran it, the output was what they expected. Really they did everything correctly, except for the fact that they were wrong. This article is addressing the next level up from RTFM. Given a dev that is reading the manual, how can it be optimised such that they can learn to use the tool correctly? How can project standards be defined so that eg, fiddly date formatting code doesn’t need to be repeated?

xtrapolate 8y ago

> "But maybe I'm wrong." I don't think you are wrong. Timing APIs are tricky and complicated. The small print really matters. Experienced engineers will know this, and so the answer in this instance, as annoying as it may be - absolutely RTFM. Also, funky documentation/APIs exist everywhere, unfortunately. Quoting the article: > "You're a new coder, and you find yourself tasked with taking a Unix time_t type value and turning it into some kind of human-readable format" I'd argue that's exactly the kind of mistakes inexperienced coders are prone to make. Hence we have code-reviews.

ygra 8y ago

I think the problem in such situations is that the M needs to address two different use cases: 1. Reference for what exists. This is used by people who don't know what %Ð is a placeholder for. Alphabetic sorting has a big advantage here. 2. Manual for what can be done. This should arguably be grouped differently, e.g. Full dates, years, months, days, etc. since there are often several placeholders for each category that are otherwise pretty far apart at times.

oblio 8y ago

> The M keeps getting bigger, and our reading time keeps getting more fractured. Also the "M"s are generally really, really bad for any practical task. I'd argue that many times they're also bad as references. They're also not indexed or hyperlinked, there's no tables or any smarter form of formatting. I know that there's also the info format but that's rarely used and it's definitely not default, many distros don't even install the tools for it... It's a really thankless job to migrate documentation so nobody's going to do it within our lifetimes, so we're stuck with man for the foreseeable future :(