What Newbies Need
It occurred to me that all the Java documentation is indexed by the solutions to problems when it really needs to be indexed by the problems.
When you don't know how to do something in Java then you also don't know how to look up the solution in the index of solutions. There really needs to be an index of problems. I should be able to look up "How to make a button turn text bold" and under that problem find "JButton boldButton = new JButton( new StyledEditorKit.BoldAction() );"
As it is, I have to know "StyledEditorKit" in order to look up "StyledEditorKit" which is the solution, which I don't know, instead of the problem which I DO know.
Which is not to say that there's anything wrong with the Java docs for someone who already knows all there is to know about the language. Only that the Java docs are utterly useless to a newbie. And, for that matter, utterly useless to anyone who has a problem to which he does not yet know the solution.
The usual piece of advice I get is "study the tutorials." Well, fine. But I don't have months to devote to learning all the classes inside and out before using the language at any level. Every programming language I've ever learned, starting with IBM S/360 mainframe assembly language in 1963 to FORTRAN to COBOL, to PASCAL, to C++ to FORTH, to BASIC, to VB, I've been able to actually be productive in that language in a few hours to a few days because once the basic syntax is mastered all that's left is being able to look up solutions indexed by problem. (e.g. "How do I erase the screen in language=X?", "What command opens a file in Language-Z?") Is it really too much to ask that I become at least somewhat productive in Java after a few months of using it by having at hand a reference indexed by problem instead of a useless one indexed by solution?
[1849 byte] By [
fiziwiga] at [2007-11-26 13:23:59]
Or you could go to the index which is linked at the top of the 1.5 API docs, press Ctrl-F, and search for "bold".
I would take issue only with this statement, "But I don't have months to devote to learning all the classes inside and out before using the language at any level."
The Java language is very simple and can be learned quickly. And if a programmer "rolls his/her own" from the basic language then productivity is achieved very quickly - albeit, at a low level.. The problem comes when we see all of these wonderfully useful prewritten classes, and things that constitute Java's libraries, and start to use them. Given the size of the libraries (how many million lines of code?), it seems reasonable to expect to spend some time learning to use them. Of course, the alternative is not to use them - But who wants to "reinvent the wheel"?
> It occurred to me that all the Java documentation is
> indexed by the solutions to problems when it really
> needs to be indexed by the problems.
>
> When you don't know how to do something in Java then
> you also don't know how to look up the solution in
> the index of solutions. There really needs to be an
> index of problems. I should be able to look up "How
> to make a button turn text bold" and under that
> problem find "JButton boldButton = new JButton( new
> StyledEditorKit.BoldAction() );"
>
> As it is, I have to know "StyledEditorKit" in order
> to look up "StyledEditorKit" which is the solution,
> which I don't know, instead of the problem which I DO
> know.
I understand your position, I know how difficult is the newbie stage. I am still a newbie in some topics, and I am not, in other topics. About your particular problem with JButton, I am a newbie, because I don磘 know anything about Swing (it磗 a swing component, isn磘 it? See? I don磘 know anything!!!). And your question, that is, how to make a button turn text bold, I consider it a valid question, because it is specific. Or maybe you can find something in google. But even after you磛e found something googling you didn磘 solve your problem, then probably you would come here in this forum again, but this time you would ask another question, even more specific than the first. And so on, until you have your problem solved.
> Which is not to say that there's anything wrong with
> the Java docs for someone who already knows all there
> is to know about the language. Only that the Java
> docs are utterly useless to a newbie.
I don磘 agree. Java docs are very important and useful, even for newbies. It can be a bit hard to be used to it at the beginning, but when you know how to search and consult the Java API docs, I磎 sure you will change your opinion.
Tip: Java is OOP (Object Oriented Programming). So, if you are having difficulties to find, for example, how to make a button turn text bold, if I were you, first I would think this way: "Which object would be able to turn the text to bold? A JButton? Would this feature fit to an object like JButton? Or would it be an object like Text, or something like that?" And thinking this way, I mean, a "OOP way of thinking" you can search in API docs. The API docs are also structured in a "OOP way", try to notice that, so that the searching becomes easier.
But note that that was just my wild guess, I really don磘 know how to turn the text to bold! As I said, I am a newbie, like you, but if I were you, I would search for an object of type Text, or JText, or something like that, because my first guess is that such a feature fits something like a Text more properly than a JButton, always having in my mind that "OOP way of thinking".
> It occurred to me that all the Java documentation is
> indexed by the solutions to problems when it really
> needs to be indexed by the problems.
That applies not just to Java documentation but to all technical documentation anywhere.
The thing is that you have to learn the discipline. Once you have, you won't want the 'index by problems', you'll only want the 'index by solutions'.
And the 'index by problems' is almost impossible to construct in practice. Which is why you have to learn the discipline.
> once the basic syntax is mastered all that's left is being able to look up solutions indexed by problem. (e.g. "How do I erase the screen in language=X?", "What command opens a file in Language-Z?")
Where did you ever encounter such an index? I''ve never seen one for any progamming system (except for FAQs, which Java has too), and I've been programming since 1971.
ejpa at 2007-7-7 17:57:10 >
> I should be able to look up "How to make a button turn text bold"
Well, no. Without knowing anything about the Java language or the Swing API it should be apparent that you have two questions there:
1. How to make a button do something.
2. How to turn text bold.
So you should seek out solutions for these two problems (which are much simpler than the combined problem) and then combine the solutions.
The following index would be essentially useless, or would have to be crossreferenced so heavily as to be effectively useless. See the following:
> "How to make a button turn text bold"
How is the text displayed? In a JTextPane, in a TextField, in a JTextField, in an OptionPane, using an HTMLDocument or some other StyledDocument? Do you plan on having a seperate Listener class, or will the Panel/Frame implement the Listener, or will you use an anonymous class?
> "How do I erase the screen in language=X?"
Clear a console? Clear the screen during a full screen apllication of some sort? Maybe make the entire screen go black during the initialization of a full screen application?
> "What command opens a file in Language-Z?"
Once again, it would depend on what type of file it is, and for what purpose it should be "opened". Is it loadLibrary, open for reading, open for writing (append or overwrite), for both reading and writing, for random/dynamic access, or simply to read from front to end?
As you can see, all of these seemingly simple questions do not work at all for an API documentation. They are, at least somewhat, applicable for a FAQ on a very basic level, when considering only the simplest application of each question without considering any extenuating circumstances. But for a complete FAQ or an API doc they are completely useless.
