Welcome to the Treehouse Community
Want to collaborate on code errors? Have bugs you need feedback on? Looking for an extra set of eyes on your latest project? Get support with fellow developers, designers, and programmers of all backgrounds and skill levels here with the Treehouse Community! While you're at it, check out some resources Treehouse students have shared here.
Looking to learn something new?
Treehouse offers a seven day free trial for new students. Get access to thousands of hours of content and join thousands of Treehouse students and alumni in the community today.
Start your free trial
Adiv Abramson
6,919 PointsWhy must documentation be inscrutable? What benefit accrues from obtuse, dense and jargon laden text?
Is there a resource that tells Java developers how to get things done using the language, in plain English? Formal documentation is self defeating since it fails to effectively convey information to the reader.
As a beginning Java programmer, I don't care about the low level details of its programming constructs and features. I am interested in getting the job done. I'd like to know if there are any common gotcha's to be aware of. And I'd like to see a couple of worked examples.
It seems that much of the Java documentation would be of interest to computer scientists but less so for computer programmers like myself, who need to figure out how to accomplish a specific task.
2 Answers
Craig Dennis
Treehouse TeacherI am with you Adiv. Have you seen the official tutorials ?
The silver lining here is this. Remember when you are writing documentation to think about all audiences. I think the author of the more intense documentation is not taking the beginner into account. Oftentimes we progress from being beginner to pro and forget what it was like trying to learn this stuff. The documentation is usually great and thorough and it just misses the beginner audience.
Let's document our code better with all audiences in mind!
Charles Williams
2,680 PointsI find that TutorialsPoint is an excellent resource for this kind of thing. They include most of the info that the Java documentation has, but they also have examples of how you can actually use it within your code and some plain English explanations. Their Arraylist page is a good example. They explain why it's useful, they show you all the methods, and then have some example code of how it can be used.