4 ms·

"Just read the docs" depends on how good the docs are, and how discoverable they are. For instance, searching for "Java read a file", I find a bunch of example

"Just read the docs" depends on how good the docs are, and how discoverable they are. For instance, searching for "Java read a file", I find a bunch of examples. And they mostly are good enough, call out when they aren't, and provide useful links. Meanwhile, navigating Oracle's website is a nightmare. https://docs.oracle.com/javase/tutorial/essential/io/file.html https://docs.oracle.com/javase/tutorial/essential/io/file.ht... exists, and is actually pretty helpful, but the only way I was able to find it was by Googling "oracle java read a file". Searching Oracle's own doc site (itself hard to find for a given version of Java) with the same string (i.e., 'read a file') turned up nothing useful ( https://docs.oracle.com/search/?q=read+a+file&category=java&product=en%2Fjava%2Fjavase%2F16 https://docs.oracle.com/search/?q=read+a+file&category=java&... )

net_greybeard 6y ago
Obviously. If the docs are garbage then you are going to have to find alternatives. However these days devs have never had it better.
- Ygg2 6y ago
  Laughs in shitty Oracle docs.
  - net_greybeard 6y ago
    I've worked in a lot of places where there were no docs and nobody knew how any worked. So be thankful that you have some docs.
    - Ygg2 6y ago
      And I've worked with auto generated meta code in Java 1.3. In practice, difference between it and Oracle docs was negligible. Hell. Their auto-gen code was more self explanatory than Oracle Java Docs.
      - lostcolony 6y ago
        I personally enjoy the Javadocs that tell me nothing about how to use the damn thing. Spending hours poring over it, with no examples, just a generated Javaoc version of the static types my IDE would have told me, and through much trial and error, I eventually figure out that I need - new Doer(UnrelatedFactory.create("foo", new WTFBar(), 5, null, null), RandomEnumFromADifferentPackage.MEANINGLESS_VALUE, true).do() But I'm not really convinced such documents are helpful. I mean, technically they're better than nothing (as in, literally better than nothing), but the difference between nothing and those docs is so small it approaches nothing ('as the worthlessness of the documentation approaches infinity the value of reading them approaches nothing', as it were)
mywittyname 6y ago
A developer who is new to a technology absolutely needs to read the documents. No matter how good or bad, it's important because it probably tells you a lot of stuff you wouldn't learn on your own (or that someone else will teach you wrong). I do a lot of GCP work anymore, and the amount of devs who make service authentication way more complicated than it needs to be is really freaking high. It's clear that the people who kicked off the project are pulling blocks from SO rather than RTFM because the FM has a simple decision tree for how to use authentication. Reading through the docs could have saved these projects each hours of time, simplified deployment and reduced the security risks associated with passing around json auth tokens (or worse: checking them into VCS.
- madacol 6y ago
  Cases where docs are not enough: - Beginners do not understand doc's jargon, or they need to learn too much stuffs to understand it that they'd rather quit. So they end up relying on third party sources/implementations - No English knowledge and no translations
  - oneplane 6y ago
    On the other hand: if you are developing software, you're going to have to be able to at least read English, and if you don't understand the jargon, that just means that your starting point isn't just the docs, but also a jargon lookup. People generally just want to cut corners and 'be done with it' which simply results in lower quality.
  - bordercases 6y ago
    - Tough luck - this is actually a trap for beginning learners so although there is wisdom in learning enough to get the job done, if they rather quit than progress in their knowledge, and the knowledge is foundational for much of their work, they are setting themselves up for long-term failure. - Fair point, English is still a lingua franca so over time this issue nils out.
  - pjmlp 6y ago
    Lacking ability to read books.
pjmlp 6y ago
Ever heard of an high technology with durable storage longer than most digital mediums called books?
aspaceman 6y ago
Sometimes you have to read the docs “But the docs are poorly written” you say “But the docs aren’t maintained well” you say Read the docs. Sometimes it isn’t supposed to be easy. Or fun. Or fit together well. But that’s the job. RTFM is the best technical advice I’ve been given and can give.
SkyPuncher 6y ago
I've often found "read the docs" leaves you with too many options for many libraries. A lot of libraries have community preferences that aren't captured in the docs. If you pick the non-standard implementation, you may paint yourself into a corner with plugins and maintenance - even though the way you choose is completely sufficient.

net_greybeard 6y ago

Obviously. If the docs are garbage then you are going to have to find alternatives. However these days devs have never had it better.

Ygg2 6y ago
Laughs in shitty Oracle docs.
- net_greybeard 6y ago
  I've worked in a lot of places where there were no docs and nobody knew how any worked. So be thankful that you have some docs.
  - Ygg2 6y ago
    And I've worked with auto generated meta code in Java 1.3. In practice, difference between it and Oracle docs was negligible. Hell. Their auto-gen code was more self explanatory than Oracle Java Docs.
    - lostcolony 6y ago
      I personally enjoy the Javadocs that tell me nothing about how to use the damn thing. Spending hours poring over it, with no examples, just a generated Javaoc version of the static types my IDE would have told me, and through much trial and error, I eventually figure out that I need - new Doer(UnrelatedFactory.create("foo", new WTFBar(), 5, null, null), RandomEnumFromADifferentPackage.MEANINGLESS_VALUE, true).do() But I'm not really convinced such documents are helpful. I mean, technically they're better than nothing (as in, literally better than nothing), but the difference between nothing and those docs is so small it approaches nothing ('as the worthlessness of the documentation approaches infinity the value of reading them approaches nothing', as it were)

mywittyname 6y ago

A developer who is new to a technology absolutely needs to read the documents. No matter how good or bad, it's important because it probably tells you a lot of stuff you wouldn't learn on your own (or that someone else will teach you wrong). I do a lot of GCP work anymore, and the amount of devs who make service authentication way more complicated than it needs to be is really freaking high. It's clear that the people who kicked off the project are pulling blocks from SO rather than RTFM because the FM has a simple decision tree for how to use authentication. Reading through the docs could have saved these projects each hours of time, simplified deployment and reduced the security risks associated with passing around json auth tokens (or worse: checking them into VCS.

madacol 6y ago
Cases where docs are not enough: - Beginners do not understand doc's jargon, or they need to learn too much stuffs to understand it that they'd rather quit. So they end up relying on third party sources/implementations - No English knowledge and no translations
- oneplane 6y ago
  On the other hand: if you are developing software, you're going to have to be able to at least read English, and if you don't understand the jargon, that just means that your starting point isn't just the docs, but also a jargon lookup. People generally just want to cut corners and 'be done with it' which simply results in lower quality.
- bordercases 6y ago
  - Tough luck - this is actually a trap for beginning learners so although there is wisdom in learning enough to get the job done, if they rather quit than progress in their knowledge, and the knowledge is foundational for much of their work, they are setting themselves up for long-term failure. - Fair point, English is still a lingua franca so over time this issue nils out.
- pjmlp 6y ago
  Lacking ability to read books.

pjmlp 6y ago

Ever heard of an high technology with durable storage longer than most digital mediums called books?

aspaceman 6y ago

Sometimes you have to read the docs “But the docs are poorly written” you say “But the docs aren’t maintained well” you say Read the docs. Sometimes it isn’t supposed to be easy. Or fun. Or fit together well. But that’s the job. RTFM is the best technical advice I’ve been given and can give.

SkyPuncher 6y ago

I've often found "read the docs" leaves you with too many options for many libraries. A lot of libraries have community preferences that aren't captured in the docs. If you pick the non-standard implementation, you may paint yourself into a corner with plugins and maintenance - even though the way you choose is completely sufficient.