Feedback

Hi, I have been in Java for a long time but just getting into the world of desktop development and hardware acceleration and OpenGL and found JogAmp in my searches.  It appears to be just what I am looking for.  However, I find it may be impossible for me to actually try to implement it into my development.

I am also a developer so I totally understand the adversion to having to take the time to do documentation.  It is also usually at the bottom of my to-do list.  However, there are times that documentation is just as essential as the code itself.  In my case I have a project to complete.  I don't have time to emerse myself in the code for an API just to figure out how it works.  Yes, examples help, but they don't provide the in depth description of why you use certain features of the API and how they work.  A JavaDoc helps define the API but still does not provide the overall picture of why you do certain things.  I am sure that the pure Java geeks just love taking the source and building their own executables.  But it is time consumming and a distraction for a developer just looking for an api to help with a bigger solution.

This is not intended to be criticism.  Just feedback.  It appears that this API could become a significant presence in the area of high performance application development.  But without a decent user document it may be bypassed by a significant number of developers.  We need an API that allows us to accomplish what we need to accomplish without having to "look under the hood" and figure out the API ourselves.  That sort of defeats the purpose of the API.  There have been a lot of good developer products die because of this sort of thing.

One suggestion that will come up is why not just use the example code?  They would be right of course.  Example code really gives a nice introduction to how to use an API.  But example code generally is written for the easiest and most obvious case.  The first time a new users tries to implement code based on the example and needs to do something different they are still stuck trying to figure out how the API works.

I may get flamed by the purists in the forum.  It would be nice to spend the next 3-4 weeks digging into the code and learning out to make it work.  The trouble is, by then I need to have a proof of concept application working that USES this sort of API.  And, again, I think that defeats the entire purpose of having the API in the first place.

I appreciate those who contribute their time and effort into these projects.  With good user documentation the acceptance of the product will be MUCH greater and growth of its usage much faster.  Just my humble 2 cents worth.

what kind of documentation would you like to read? Sure we could improve documentation for key parts like initialization and some jogl concepts and APIs.

But if you would like to read basic OpenGL tutorials or documentation you would be better served with an GL book (since there is not that much difference between C and java+jogl as soon you begin rendering).

main problem is time... as always but thanks for the feedback,
so if you  could write a few things down (e.g via a blog entry) while you are learning jogl... this would be great.

best regards,

michael

On 07/19/2010 04:53 PM, kyjava [via jogamp] wrote:

Hi, I have been in Java for a long time but just getting into the world of desktop development and hardware acceleration and OpenGL and found JogAmp in my searches.  It appears to be just what I am looking for.  However, I find it may be impossible for me to actually try to implement it into my development.

I am also a developer so I totally understand the adversion to having to take the time to do documentation.  It is also usually at the bottom of my to-do list.  However, there are times that documentation is just as essential as the code itself.  In my case I have a project to complete.  I don't have time to emerse myself in the code for an API just to figure out how it works.  Yes, examples help, but they don't provide the in depth description of why you use certain features of the API and how they work.  A JavaDoc helps define the API but still does not provide the overall picture of why you do certain things.  I am sure that the pure Java geeks just love taking the source and building their own executables.  But it is time consumming and a distraction for a developer just looking for an api to help with a bigger solution.

This is not intended to be criticism.  Just feedback.  It appears that this API could become a significant presence in the area of high performance application development.  But without a decent user document it may be bypassed by a significant number of developers.  We need an API that allows us to accomplish what we need to accomplish without having to "look under the hood" and figure out the API ourselves.  That sort of defeats the purpose of the API.  There have been a lot of good developer products die because of this sort of thing.

One suggestion that will come up is why not just use the example code?  They would be right of course.  Example code really gives a nice introduction to how to use an API.  But example code generally is written for the easiest and most obvious case.  The first time a new users tries to implement code based on the example and needs to do something different they are still stuck trying to figure out how the API works.

I may get flamed by the purists in the forum.  It would be nice to spend the next 3-4 weeks digging into the code and learning out to make it work.  The trouble is, by then I need to have a proof of concept application working that USES this sort of API.  And, again, I think that defeats the entire purpose of having the API in the first place.

I appreciate those who contribute their time and effort into these projects.  With good user documentation the acceptance of the product will be MUCH greater and growth of its usage much faster.  Just my humble 2 cents worth.

---

View message @ http://jogamp.762907.n3.nabble.com/Feedback-tp978714p978714.html
To start a new topic under jogamp, email [hidden email]
To unsubscribe from jogamp, click here.