3 ms·

As an intermediate developer I still have trouble with many source documentation. . It's a problem of information density- I don't know where on the page to get

As an intermediate developer I still have trouble with many source documentation. . It's a problem of information density- I don't know where on the page to get what I need, or the documentation examples have very basic implementation that don't cover my use case. And as a beginning developer you don't have the library of personal experience to work-around use cases. Usually I have to find a third party simplified documentation sites, like dotnetperls or ss64, which have easy to read documentation. Besides, at least with SO, it clearly states to search before you ask. The user is only asking because searching wasn't successful. An answer of "go search more" does not help the asker.

douche 11y ago
There's also the problem that so much documentation is just straight auto-generated javadocs or xmldocs, with nothing beyond what you'd get looking at the method signatures. MSDN is better than most, but there's still a ton in there in places that has no examples or usage information, no indication of what valid inputs are, no indication of any other external state that could derp things up.
metaphorm 11y ago
learning how to read technical documentation is a skill in its own right, and we all need to practice it in order to get good at it. obviously some documentation is better than others, and asking specific questions to fill in the gaps where documentation is unclear is a good thing to do. however, programming is very much driven by learning how to find the answers to problems on your own. often those answers are in the documentation but not always. sometimes they haven't been answered by anyone before and learning how to extrapolate from documentation to understand the behavior of programs in new situations is a skill that has to be developed. and of course, ultimately, the final authoritative document on how a program will behave is the code itself. there are times when you have to read source. hopefully those are rare occasions, but being capable of doing it when necessary is yet another skill that needs to be developed. reading through an unfamiliar codebase is difficult and requires practice and experience. all of these technical reading skills need to be practiced. beginners frequently make the mistake of denying themselves opportunities to practice those skills by simply asking for someone to tell them the answer.
- badloginagain 11y ago
  > all of these technical reading skills need to be practiced. beginners frequently make the mistake of denying themselves opportunities to practice those skills by simply asking for someone to tell them the answer. These are skills that develop over a programmers career. And when you have issues like getting a for loop going, or if you can have a for loop in a while loop, then reading the documentation is not going to be very useful. Again, information density and assumed level of programming competence in source documentation won't help if you are trying to figure out fundamental programming issues. Should people read documentation, of course, but the usefulness of documentation increases with programming ability.
  - metaphorm 11y ago
    I agree. Total beginners do deserve more patience and more explicit instruction. Novice and Intermediate programmers who have learned the basics and are looking to learn more are the ones who really need the practice in "learning how to find your own answer".

douche 11y ago

There's also the problem that so much documentation is just straight auto-generated javadocs or xmldocs, with nothing beyond what you'd get looking at the method signatures. MSDN is better than most, but there's still a ton in there in places that has no examples or usage information, no indication of what valid inputs are, no indication of any other external state that could derp things up.

metaphorm 11y ago

learning how to read technical documentation is a skill in its own right, and we all need to practice it in order to get good at it. obviously some documentation is better than others, and asking specific questions to fill in the gaps where documentation is unclear is a good thing to do. however, programming is very much driven by learning how to find the answers to problems on your own. often those answers are in the documentation but not always. sometimes they haven't been answered by anyone before and learning how to extrapolate from documentation to understand the behavior of programs in new situations is a skill that has to be developed. and of course, ultimately, the final authoritative document on how a program will behave is the code itself. there are times when you have to read source. hopefully those are rare occasions, but being capable of doing it when necessary is yet another skill that needs to be developed. reading through an unfamiliar codebase is difficult and requires practice and experience. all of these technical reading skills need to be practiced. beginners frequently make the mistake of denying themselves opportunities to practice those skills by simply asking for someone to tell them the answer.

badloginagain 11y ago
> all of these technical reading skills need to be practiced. beginners frequently make the mistake of denying themselves opportunities to practice those skills by simply asking for someone to tell them the answer. These are skills that develop over a programmers career. And when you have issues like getting a for loop going, or if you can have a for loop in a while loop, then reading the documentation is not going to be very useful. Again, information density and assumed level of programming competence in source documentation won't help if you are trying to figure out fundamental programming issues. Should people read documentation, of course, but the usefulness of documentation increases with programming ability.
- metaphorm 11y ago
  I agree. Total beginners do deserve more patience and more explicit instruction. Novice and Intermediate programmers who have learned the basics and are looking to learn more are the ones who really need the practice in "learning how to find your own answer".