As asked for by @erlend_sh in this post, here are some very humble suggestions/points of feedback.
Notes on the jME/jMP documentation:
- A severe lack of structure (either that or I am just very unfamiliar with your intended taxonomy).
What I mean is that even though there is LOTS of VERY GOOD information on more or less every aspect of the API and platform, quite a lot of it gets lost in the way the information is organized.
- Faulty, incomplete or otherwise partial information
Several topics in the documentation only cover fractions of intended implementations/suggestions of use. Quite often the documentation does not have thought-through methods for keeping up with an ever-chaning API (alpha1,2,3,4 etc). This leads to some examples only running with parts of the intended instruction set being used. In some cases the code given in the [Tutorials & Docs] section is outright wrong due to changes made in the API.
- User un-friendly. Both in terms of browsing and in terms of searching.
I will keep it simple here. JavaDoc is not for everyone. Arguably it is not made for most “creative” people (yes I am using the term creative VERY loosly here). Having said this I am not saying that it is not a good thing for developers to read JavaDoc (it can be a very good source for learning). My point is that most if not all, non-programmers will find JavaDoc quite confusing to the point where it can get frustrating. My main source of documentation has been the JavaDoc but I would have LOVED it if there were more options.
- Lacking the ability for community comments directly linked to each class/method/data member.
For example, the PHP documentation team has done an amazing job of this.
In closing…
During the 90’s I spent many years working with (and contributing to) the Allegro API (http://alleg.sourceforge.net/stabledocs/en/allegro.html). I am not saying this documentation is perfectly structured but it has a very simple look and feel to it. It’s very easy for new developers to find exactly what they want/need to find. Maybe something like this could be part of a way forward for jME?
It’s 1AM right now… so I will reserve the right to edit this post later on. Thank you for reading and let me once again remind you. These are only my VERY humble suggestions and thoughts after being a jME3 user for about two or three months… give or take.
Thank you for all your HARD WORK. jME3 is an amazing game maker platform!
/Peter
i need a tutorial TestCustomSkeleton that shows how to create a custom skeleton.i need this because the whole bone creation api is a strange.
bone.getLocalPosition(); vs
bone.getModelSpacePosition(); vs
bone.getWorldBindInversePosition(); vs
bone.getWorldBindPosition();
Which methods do i have to call to set the skeleton ? setBindTransforms ? setBindingPose() ? setUserControl ?
TestCustomAnim doesnt even use setBindingPose() at all !!!
@tralala for tutorial requests, I suggest you start a new thread in the documentation board. This discussion is clearly geared towards the structure of the jMonkeyEngine documentation, rather than its contents.
@gasher thank you very much for the feedback. I’ll write a more detailed response later. The bottom line is that @zathras , who is the lead maintainer and driver of our documentation, is completely occupied with the upcoming jMonkeyEngine beginner’s book (coming early 2012). Meaning, any suggested change to the docs, be it regarding contents, structure or otherwise, would have to be worked in by whoever made the suggestion. I’m not trying use the open source DIY paradigm to avoid work here: it’s just the situation we’re in right now.
I’ll have to agree with @gasher here.
It’s not that the docs are bad, quite the contrary, but there’s no “path” or breadcrumbs if you want, from going to “Start” to the next step. The articles, by themselves, at least those that are not covering deprecated/removed stuff, are nicely done, mostly thorough and understandable. It’s just the overall, I’m tempted to use “indexing”, but that would be wrong, the presented structure is… well… I don’t want to rub anyone the wrong way. Let’s just say it’s not the most convivial documentation structure. It lacks ergonomics.
Anyway. I wanted to add my 2c’s worth.
hey,
gasher said:
- A severe lack of structure (either that or I am just very unfamiliar with your intended taxonomy).
I don't see the real difference between this doc http://alleg.sourceforge.net/stabledocs/en/allegro.html and this one https://wiki.jmonkeyengine.org/legacy/doku.php/jme3#tutorials_for_beginners. It looks structured the same way to me. At the beginning it's easy stuff and tutorials, and the more you get to the bottom of the page the more things are getting difficult.
I'm not trying to bash your point here, I just want to understand what do we have to change in the doc to make it more structured.
gasher said:
- Faulty, incomplete or otherwise partial information
For the deprecated stuff it's our fault I guess, I mean the core devs.
Zathras write neat documentation, and the moment she type the final dot, we changed the API to add fancy stuff etc ....
But I'm gonna invoke the "It's Alpha" thing, every change made to the API is for a greater good.
She's been very busy with the book lately, so she can't keep up the pace of changes to the API on both the book and the wiki.
With beta coming, API tend to become a lot more stable, the doc will follow that trend.
gasher said:
- User un-friendly. Both in terms of browsing and in terms of searching.
Again, in the page I linked there is a search box at the top right of the screen (maybe it should be more visible) and the structure is like an index really.
gasher said:
- Lacking the ability for community comments directly linked to each class/method/data member.
mhhh, you mean everyone could set a comment on each method? Would be quite difficult to set up i guess, but it's an interesting idea
Thanks for this feed back.
I both agree and disagree. I’m probably gonna go off-topic and talk about content, but oh well :P. I find the beginning tutorials to be very well structured and helpful, but there isn’t much support after that. Everything seems really disconnected, and there’s nothing really which joins all the dots together. I remember when I first finished all of the hello tutorials, I tried to implement something myself, and just failed. I think there should be like a 10 part tutorial (or something) on how to actually complete a whole game, doesn’t have to be advanced, just which incorporates all of the hello tutorials as well as Nifty GUI together. It would show proper class/package structure, and give people a heads up on what is good practice. Also you need to mention bulletAppState.getPhysicsSpace().enableDebug(true) a lot earlier. Its almost at the very end of the advanced section, when it should be a recommended thing from the get go, for physics based games.
Everyone: Thank you for your feedback. I will take it upon myself to paint a clearer picture of how I would like the documentation for jME to look like.
Particulars @nehon: I believe there are several tools available to facilitate the kind of (extremely) flexible documentation viewport that I am speaking of. In my world I see the javadoc compilation lying at the heart of the matter. A somewhat customized plugin for wordpress will then interpret and process the latest javadoc for a certain particular and will therefor present the latest (I assume javadoc is recreated in each nightly build?) low-level documentation on every new page request. In combination with css-customization, examples section and a simple comment field at the bottom of the page, I think any developer would have everything he or she needs in order to find, search and understand the docs.
Suggested main or sub -index overview (in sections):
- Grand overview of items. Ordered by area of intended usage. ( i.e. Keyboard, Init, Scene graph, Sound, Loading and saving data files… etc etc etc)
- Relevant links.
- Community generated content (each entry denominated with current version information of the API)
Suggested page overview (in sections):
- JavaDoc for a certain particular. (perhaps some minimal re-formating with css needed)
- Instructions for intended usage. (the dev-team’s (or doc-team’s) own comments or suggestions on usage)
- Relevant links. (both internal and external links (if such links exist for this particular) )
- Community generated content (each entry denominated with current version information of the API)
Please tell me what you think. Thank you.
gasher said:Sounds pretty darn cool. If that's something you're capable of creating then by all means take a stab at it. Are you making this suggestion under the assumption that our JavaDoc will soon be updated to Java 7, with the greatly improved styling features?
(...) A somewhat customized plugin for wordpress will then interpret and process the latest javadoc for a certain particular and will therefor present the latest (I assume javadoc is recreated in each nightly build?) low-level documentation on every new page request. In combination with css-customization, examples section and a simple comment field at the bottom of the page, I think any developer would have everything he or she needs in order to find, search and understand the docs.
I've yet to hear back from @sbook regarding when this will happen. In spite of the recent announcement, Java 7 is not publicly available for download yet...
1) Grand overview of items. Ordered by area of intended usage. ( i.e. Keyboard, Init, Scene graph, Sound, Loading and saving data files... etc etc etc)
I'm unable to visualize how this would be different from what we're already doing with the jME3 doc index.
2) Relevant links.As in, to other related articles?
3) Community generated content (each entry denominated with current version information of the API)What do you mean by community generated content? Any examples? Are you referring to the code & projects sporadically posted on the forum?
I can see your suggestions being a great improvement, but I'm still having some trouble envisioning exactly what we'd be looking at. If you could visualize these overview pages of yours, be it on paper, with Paint or a tool like GoMockingbird (recommended!), that would help a lot.
On a somewhat related note, a simple little addition that could help quite a bit would be a "Report broken page" button which would redirect users to #new-post on this Documentation board.
I think it would be very useful to have the FlagRush tutorial from jME2 ported to jME3. It was a very good way to learn how to create a simple but also complete game.
@gasher :
Thanks for spending time to help us improve things! I’m not fully satisfied with the navigation and the wiki either. I have the same question as Erlend, I cannot yet visualize what exactly you mean.
I agree that a) writing better javadoc and b) integrating it better would is a needed step. The jme2 wiki used to treat java classes as WikiWords and linked them to javadoc. If we recreate that feature, would that partially help?
I’m aware that the wiki isn’t 100% current – most of it is drafts that I jotted down just because someone asked for it. I feel the urge to take a month off and rewrite everything, but in reality I have a day job to go to. This is definitely not the final version.
In my defense, I started improving the docs by adding images and tags, but for a while now, the wiki has not been loading any images, and the editor is so buggy that every change has weird repercussions. Can @sbook reinstall it? Start from scratch and copy the content back in? I don’t like the stylesheet either, I don’t even know where to start. 
@Vortex : Regarding the ever famous “Flag Rush”: I do intend to write an end-to-end tutorial (scenario) like JME2’s Flag Rush. These things are excellent for reading – but very hard (time intensive) to write. I’m not a developer, I don’t simply write a “real” app over the weekend, unfortunately. I haven’t started writing this end-to-end tutorial, because I would have to completely rewrite it by now anyway, that thought was slightly dicouraging. Instead I started collecting best practices.
@wezrule : I added a tip to use the physics debug line now in several spots, thanks, that’s the kind of comments we need!
@gasher : Elsewhere you described your idea for a docs page as follows:
Top: API reference information, collected RIGHT out of the automated documentation system
Middle: Dev / Doc team suggestion for usage (plus example+demo)
Bottom: Community interaction (forum integration?)
Can you give an example based on http://hub.jmonkeyengine.org/javadoc/ ?
@zathras: Hi.
I will give a simple example, one I use often when explaining this type of documentation system.
Two cases:
jQuery - http://api.jquery.com/category/traversing/
Go to the page. Click on… let’s say .each() function. This page is a similar view. Documentation information (pulled from auto generated file) at the top. Followed by dev/doc -team comments on intended usage in middle section. Ending with community generated content (i.e. comments and/or links).
PHP - http://www.php.net/manual/en/function.implode.php
Same thing as stated above.
Remember whatever system you create it needs to be able to output plain html so the content can be added automatically to the jMP JavaHelp system.
@normen: Are you refering to the use of specific client or server side scripting?
If you are able. Please provide additional information regarding the jMP javahelp system. Are there specifics which need to be taken into account? By principle I do not see how this can be an issue but I am interested in understanding the full picture. Thank you.
Right now an ant task downloads all wiki pages which are stored in a config file using dokuwikis htmlbody renderer incl. images and then adds them to the index of the JavaHelp (search box/F1 in jMP). The practical thing about dokuwiki is that it uses namespaces which can easily be converted to package names for the help pages. This way the whole wiki content is available and searchable right in the help system of the IDE and its always the right documentation for that specific version of jme3 which is installed (the wiki contains the files that are updated according to the svn version of jme3). The javadoc is integrated in the IDE anyway.
I am not quite sure what the initial problem is though. The manual content is easily searchable to find specific topics, it has a table of contents to navigate to specific topics and the javadoc automatically pops up when you type a methods name… I also cant really agree that the main wiki documentation page is unclear in its structure if you talk about the online wiki. Questioning the use of JavaDoc almost seems naive to me. But if you see room for improvement thats fine, don’t take my german directness as negative criticism, its supposed to be constructive 
I see your point normen. I obviously agree wholeheartedly that javadoc is very good for a skilled developer and also good for an aspiring developer. Maybe I should take caution before proceeding further with this documentation alteration. I value your insight and will stand by if the need for a change in documentation should arise.
I didn’t mean to bring all the efforts to a halt, its mainly about the requirements for the JavaHelp system and the fact that I think the “logic” in the presentation will always have to be something human-guided.
Something where people can contribute to javadoc as well as written documentation easily would certainly be great and I was thinking about creating a plugin that allows easy editing of the jme3 javadoc - just like a wiki - myself. But hoping to join it to a point where you find an appropriate class to store the javadoc for a general topic like multithreading is a bit far-reaching I guess…
If there was something like the wiki where one can easily integrate whole packages of related javadoc (e.g. as a link-table) as well as the text of certain javadoc’d methods within the written text of the page, that would be great. Still we are already going along necessities here, so its mainly about getting it back to a working state at the moment (e.g. image links, broken wiki editing due to javascript errors).
I love and hate JME! I really appreciate your hard work on this. I’d like to see my own difficulties become an opportunity to spare other users these problems. Documentation is a big one, both in “big picture” descriptions of the SDK and in the Javadoc.
JME2/JME3
There are many issues created by these two similar-but-not-the-same offerings being on the same site. Anything that could be done to stamp all content as being one, the other, or both would help - so that forums and searches offer less information that must be examined and rejected if it is not pertinent to the reader.
Javadoc clarity and completeness
There are a lot of places where the Javadoc fails to explain a function. Some of these also seem terrible when the details are what some users would find inconsistent with other functions. Here are two examples.
Spatial.move() in its various flavors causes the translation relative to the parent Node to change… but in which coordinate system is the displacement expressed? The parent’s? The spatial’s? It turns out it is the parent’s. This is not clear, and it contradicts Spatial.rotate() (see below). For the sake of completeness, it would be nice if there were one that interpreted the vector provided as being in the spatial’s own space, which I right now have (with minimal testing – I invite correction) as:
// move the spatial by the provided vector, which is expressed in the spatial’s own coordinate system
// rather than its parent’s
public final static void moveInOwnSpace(Spatial spatial, Vector3f v) {
// transform V from own space to parent’s space
v = spatial.getLocalTransform().transformVector(v, null).subtractLocal(spatial.getLocalTranslation());
spatial.move(v);
}
Spatial.rotate(), on the other hand, seems to rotate the object about its origin and through its own axes, rather than its parent’s. Improving the Javadoc would ease confusion, as many IDEs offer breezy access to these. While I’m on the topic, Spatial.rotate(float yaw, float roll, float pitch) has all 3 of its arguments named wrongly. Rotation about X is pitch, rotation about Y is yaw, and about Z is roll.
Target Audience
3D is math, and math that many people find unintuitive. While it must remain in place, obviously, JME’s Javadocs customarily pass on opportunities to express in game development terms how various functions are used. For instance, Quaternion.mult(Quaternion) has a sensible name for what it does mathematically, but math is a means, and not an end. Minimally, greater emphasis in the Javadoc should explain that this is how a series of rotations are applied.
I’m afraid to even guess what Quaternion.getRotationColumn() does. Its Javadoc is written for mathematicians and not for people trying to figure out which way is “left”. The second category of user is really the target demographic, isn’t it? It might not be suitable to remove the content already in place there, but spelling out the practical application of a rotation column would be a super enhancement, e.g. (I am guessing at the function’s meaning here… the character of the information I’m tossing in is the point) “Getting the column AXIS_X, for instance, will return a Vector3f expressing which way the Quaternion’s positive X (typically, “right”) axis is expressed in the coordinate space the Quaternion’s rotation is effected in. The Vector3f will not, however, be normalized.” etc, etc
tone