Suggestions to the jME3 documentation (18 posts)

  • Profile picture of gasher gasher6p said 9 months, 2 weeks ago:

    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

    #
  • Profile picture of tralala tralala24p said 9 months, 2 weeks ago:

    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 !!!

    #
  • Profile picture of erlend_sh erlend_sh132p said 9 months, 2 weeks ago:

    @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.

    #
  • Profile picture of madjack madjack487p said 9 months, 2 weeks ago:

    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.

    #
  • Profile picture of nehon nehon590p said 9 months, 2 weeks ago:

    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 http://jmonkeyengine.org/wiki/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.

    #
  • Profile picture of wezrule wezrule190p said 9 months, 2 weeks ago:

    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.

    #
  • Profile picture of gasher gasher6p said 9 months, 2 weeks ago:

    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):
    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)
    2) Relevant links.
    3) Community generated content (each entry denominated with current version information of the API)

    Suggested page overview (in sections):
    1) JavaDoc for a certain particular. (perhaps some minimal re-formating with css needed)
    2) Instructions for intended usage. (the dev-team’s (or doc-team’s) own comments or suggestions on usage)
    3) Relevant links. (both internal and external links (if such links exist for this particular) )
    4) Community generated content (each entry denominated with current version information of the API)

    Please tell me what you think. Thank you.

    #
  • Profile picture of erlend_sh erlend_sh132p said 9 months, 2 weeks ago:

    gasher said:
    (…) 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.

    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?

    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.

    #
  • Profile picture of Vortex Vortex9p said 9 months, 2 weeks ago:

    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.

    #
  • Profile picture of zathras zathras31p said 9 months, 2 weeks ago:

    @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!

    #
  • Profile picture of zathras zathras31p said 9 months, 2 weeks ago:

    @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://jmonkeyengine.org/javadoc/ ?

    #
  • Profile picture of gasher gasher6p said 9 months, 2 weeks ago:

    @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.

    #
  • Profile picture of normen normen1271p said 9 months, 2 weeks ago:

    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.

    #
  • Profile picture of gasher gasher6p said 9 months, 2 weeks ago:

    @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.

    #
  • Profile picture of normen normen1271p said 9 months, 2 weeks ago:

    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 :)

    #