Kokul’s World

For the past four months now, I have been learning Java as part of my computer science curriculum in Grade 12 high school. While Java has given me a taste of multi-platform programming, it also has revealed what I have considered quite a big flaw. That is the lack of documentation.

For a beginner like I, this makes learning more advanced topics quite daunting. I’m not saying that this problem lies with just Java, I can say it also is a problem with learning the Win32 API, or learning how to do some of the more advanced things in Linux. There just isn’t enough documentation for beginners. Sure there is documentation that people who have spent quite a bit of time in Java can understand, but never any for those who are trying to do something new and different with the language.

Now some may argue that there are dozens of sites dedicated to providing tutorials and resources to programmers. I do agree, they are quite useful. However almost all of such sites I have stumbled across have provided tutorials, but they often consist of one giant java file, with some comments. This is fine for some, but for beginners like I, this is quite daunting. After all, some of those commands and structures I have never seen before. Also, it is hard to adapt an example to your own program when the commenting in the example is so sparse, you don’t know what a particular piece of code is doing. As a result, I have spent countless hours in frustration trying to make code from examples work with my own code.

So what can solve this problem? Step-by-step tutorials like what one finds in Java books. Instead of just dumping a huge amount of sample code for us to figure out, why not just run through one block at a time, explaining the importance of certain methods, why they are needed, and how they work with other methods. It would make a beginner’s life much easier, and discourage fewer people from dropping learning the language.

Another main complaint I have with the documentation is Sun Microsystems’ own API docs. The docs they provide for their JDKs and the Java Media Framework is… well… let’s say not detailed. Sure they outline what the method and class does, but they never explain how to implement methods properly. The descriptions can also be a bit lacking. For example, the descriptions sometimes lack describing the limitations of certain methods. Also, the docs fail to explain how one method is dependant on another method or class from the same package!

Listen, I know programmers don’t like writing documentation for their work. I hate doing it as well. But what one must understand is that you are writing that documentation for the benefit of someone else who is looking at your code. To you, you can understand your code in a flash, but how about someone who is helping you with your project, or someone who is trying to learn from you? You make it quite a daunting and difficult task without proper documentation and detail.

Dear Sun Microsystems, while I do appreciate how cool Java is, being platform independent, it is really hard for me to embrace it as the language to use when you do not help make my learning experience with my language a bit easier.