Using Oracle's Java Documentation as a Teaching Tool

Question

I'm in the process of preparing for the second semester of AP CS A (Java). I want to review objects and classes with my students to prepare for our extended focus this semester on inheritance and interfaces. I've been using textbooks I'm not particularly thrilled with, so I wanted to put together some review material of my own and/or from other sources.

My first Google took my right away to the official documentation from Oracle, and I found it to be a clean, easy-to-understand explanation of fundamental concepts of the language (which can't always be said for documentation). In particular, this section on Object-Oriented Programming Concepts is exactly what I was looking for in terms of simple, clear explanations with code samples. That lead me to ponder the following question...

What, if any, benefits are there for teaching straight from documentation rather than a textbook?

Answer 1

One obvious benefit, which is really a good goal in and of itself, is that students get used to utilizing documentation. Many students don't use the internet as a resource at all, and those that do often wind up on StackOverflow. It has been my experience that the very basic searches that those students often perform wind up at SO pages that are rather too complex. If they want to know how to find a subset of a String in Java, the Oracle documentation is really a better place to begin than Google.

Being able to read and understand documentation gives them a powerful research tool that they can utilize for future explorations.

Answer 2

I will ask some rhetorical questions below - they aren't meant to be snarky.

That, of course, depends on the textbook. I would think that the documentation alone would be a terrible idea. Would you teach a class in Shop by giving each student a box of tools and no instruction? The quality of the official documentation is, as you note, excellent, but there is nothing there about how to use it - about how to actually program.

How would a student, faced with a project or a programming goal even begin to know where to begin in decomposing the problem into manageable chunks. Language documentation doesn't help with that - though of course, some text books don't either, just focusing on language tools.

But a good plan is to use the documentation along with a site like SO in conjunction with a good textbook and your own skill.

The problem decomposition is just as hard as the solution synthesis, and if the students are skilled in some paradigm other than OO, they will just hack code according to their older skills and learn very little about the essence of Java. The page you pointed to is just definitions. It won't help anyone build skill. Would you teach a composition class giving students a dictionary and nothing else?

Yes, a class is .... BUT, how do I create a good class? What granularity of decomposition should I use? How do I gain skill in the various idioms of Java specifically and OO more generally? What simple (or complex) design patterns can be used to solve this problem?

None of that will likely be found in the documentation, no matter how good. Use the documentation, but not exclusively. The interconnections are more important than the things actually discussed.

Answer 3

You shouldn't teach from just documentation or just a textbook. You should teach from both. You should also include in-class live coding sessions and general lectures as well.

Each of these things is a tool that covers a different aspect of what students need to be learning. Textbooks can be great for providing a high-level overview. Documentation can be great for providing more details when you need a reference. Live coding sessions can be great for showing the students how to actually write code, and lectures tie it all together.

I will say that including documentation is a great idea. Students should know, from day one, how to look stuff up in the reference, how to consult JavaDoc, and how to read online tutorials. Properly using these resources should be a part of the very first homework assignment. This is a crucial step that I think a lot of programming curriculum leaves out, so kudos for including it.

The problem with documentation is that it's often incomplete from a learning perspective. It's meant to be a reference, without the background knowledge that's required to truly understand how to actually write code to solve a problem. The documentation you cite provides a very brief overview of the various topics, but it doesn't take the deep dive that you need to actually learn about OOP.

That's where a good textbook would come in handy.

Answer 4

If you are teaching Java, you need to start with the API guide early and often. Begin with the method section which answers, "What kind of work can I get an object to do for me?" As we progress through topics such as inheritance and interfaces, we keep going back to the guide and learn how those are reflected in the documentation. An important goal: A student should be able to read most or all of the documentation and use it to solve a programming program by the end of the course. It is the primo teaching tool.

Students who take Java at NCSSM are generally good Python programmers. Early in the class we discuss the type system and compare the Javadocs to those of Python as well as comparing the types and how the languages are similar and how they differ (ex: duck vs. static typing).

I use my own unpublished book for the class because it is uniquely suited to our program and it does not contain the lard, boxes, and nonsense that most committee-written leviathan tomes contain. It covers quite a bit of material on building GUI applications using the JavaFX8/9 framework.

We do lots of "live" coding in class. Got a jam? Use the API guide to figure it out. We also use Java9's wonderful JShell a lot. It's an amazing teaching tool.