Hi!
I’ve noticed there are many posts from new users here in the forums, and its nice seeing new users finding this great peace of software!
Many questions would not have to be asked if every one used the tutorials (and docs), because most of them are great. Somehow newcomers miss the tutorials or just skip them because they are lazy…
One reason might be because they are kind of hard to find on the hub.jmonkeyengine.org landing page. Most stuff there is only interesting once already in the community, like the blog (I know it’s the community page). Maybe one could make better use of it somehow?
Maybe one could include the tutorials as a “project template” like the test suite in JMP, making the tutorials even more dead simple to get started with?
Why jmonkeyengine.com? What’s the point of having two websites? I think it would be better to merge them in some way. 
@kwando said:
Somehow newcomers miss the tutorials or just skip them because they are lazy...
For most its definitely because they are lazy, they don't even bother to read them when I post a direct link and urge them to read the tutorial completely and best do them all to get a good basic overview. Most people that post such basic questions probably just downloaded the SDK with some idea in their heads and at best want the code they need directly done and posted by somebody else. If they at all look at the tutorials then its only when it contains the exact code they need (e.g. the mouse picking example is one they actually read, the node one not so much though it contains lots of info on how the scenegraph works).
Note that some even start their threads with a comment that they "don't just want a link to 'math for dummies'" even though they ask the exact questions that are explained in there, so its definitely not about finding them I think ;) What might be an issue is that most people (including myself) instinctively rather use google than site-specific search tools which obviously yields less proper information.. I think both jme.com and jme.org make it easy to access the Documentation (its a main link on both pages after all), the separation is mostly for allowing a proper introduction of the project without distraction through too much community / developer-relevant information.
I myself (like you apparently as well) didn't have any issues finding information and documentation already in jME2 times, we also have way less basic questions (about jME3) in general since the documentation has been completed. You can create a project with all runnable tests using the SDK, a BasicGame project already displays a box (tier 1 tutorial already there ;)), the search function of the SDK contains all info from the wiki.. I think we basically wipe the users *ss documentation wise.. And we do plan to have template projects for certain game types (FPS, networked FPS, RTS etc.) at some point too.. But really, people have to look around a bit and I think most developers find their way around ;)
The .com is the showcase site, and .org is the user-managed one (anyone can edit the wiki, etc). There were some discussions ages ago on why they were divided.
We could introduce the tag to the Documentation tap up top I love the blink tag.
But I think there are two types of beginner users that come here: new to game programming (sometimes new to Java), and new to jmonkeyEngine but know game programming.
I think the tutorials and docs are best suited for the second group. The first group has some major hurtles that project templates won’t solve. We have talked about project templates before, and it often comes down to who will maintain them.
Your ideas are good though, and I do think some of the tutorials and docs should be linked to more frequently throughout the site.
@erlend_sh always has good ideas related to this.
I agree about the websites getting merged. The split happened for a variety of reasons during the initial transition of “ownership” when the old developers moved on to Ardor3D. I don’t really have time to go further into it.
Shortly put, what I want to do is use the Olya theme as our front page and integrate .com’s content into that. This way our landing page would be a combination of the latest news and showcase material. The community would be situated at hub.hub.jmonkeyengine.org, powered by a BuddyPress-specific theme.
That’s the stretch-goal. Realistically we’re stuck with our current set-up for at least a couple more months. First on the realistic agenda is to apply a better theme to jMonkeyEngine.org. This isn’t quite as easy as it sounds, as there aren’t a lot of fully featured and properly supported BuddyPress themes out there.
Unfortunately I’m up to my neck in work (student game project in alpha) until April 20th…
Oh and I always enjoy discussing accessibility (user paths, data structure, content delivery etc.) so by all means keep asking questions. As for solutions, the best kind of suggestion right now is one that assumes no radical changes, but improves upon what’s already there. Little things as simple as sidebar widgets.
I think JMonkey only needs more time. More time means more features, more tutorials, more forum posts and so on.
JMonkey is my first 3D Engine and I am working at so many different problems simultaneously → this generates tons of questions.
I always hope that I will find a solution searching the forum/wiki but sometimes I am not successfull. Then I am not sure weather I should open a new thread because I think every one will hate me when I ask too many questions. And as a result nobody would answer them in the future.
So I think the best way to help beginners (like me) is to answer all the questions.
jME has the best documentation i’ve ever seen.
If you try for example to begin using Ogre3D, you will see how different are documentation’s pages. The tutorials discuss every aspect of the engine from scene graph to networking passing through physics and GUI. It is an invaluable treasure of jME.
There is only one thing that i think can be helpfull and is a well documentation of the test cases. I mean a line by line comment through the code that briefly explains what is going on and (for example) where to find more information about it.
However as i said → documentation + tutorial + test + javadoc = everything you need to start
I have found only one defect in the doc of jME and it regargs the internal mechanism of the engine. I say this because if i want to master how all works i can’t do nothing other then see the source code try to understand what is happening and read the javadoc but it is not a good approach IMHO. Maybe a real skilled developer in 1 hour can understand everything of how (for example) rendering works but i’m only a junior developer XD. In my little ( 18 months ) carrier i’ve seen that when the project you will work on is well documented, the time for master it reduces drastically and such a doc is made of javadoc, source code and also UML diagram.
If for example there was a simple image showing schematically (by boxes for instance) how parts of the engine interact with each other, i would simply read the source code, check the block diagram and the uml class diagram + javadoc of classes, and find the solution of my problem / undesstand how something is done.
That is only my point of view and i hope i have not offended anyone.
My intentions was to involve the production of a well documented system that can be improved by anyone who want to do it
Here, perfect example, only thing missing is the explicit sentence “but none of the tutorials show how to replace oto with ninja” 
http://hub.jmonkeyengine.org/groups/import-assets/forum/topic/replacing-oto-with-ninja-how-would-i-do-this/#post-163507
ahahahaahha
However normen, do you think that something like what i said can be done?
Or if you know something i can study to understand what happens in jME, i will do it
How about a RTFM monkey smiley, would shorten much answers XD
@kazeshiro said:
There is only one thing that i think can be helpfull and is a well documentation of the test cases. I mean a line by line comment through the code that briefly explains what is going on and (for example) where to find more information about it.
Yea I agree here. Some of it is straight forward, but I understand the code very well. Someone new to it would often be looking at it and scratching their head.
And probably, more detailed technical tutorials on how all of the rendering works, the different buckets, material techniques, post filter processing etc. These are more of the "magical" parts of the engine for many people.
Thing is, mostly the tests are for ourselves to actually test some new function Not all of them are done 100% according to best practices but still, most OSS projects only have these kinds of examples and if you’re lucky then maybe they have a few comments ^^
What I agree on though is that we could use a more technical overview as you mentioned.
Pretty good we agree on something normen!! ahahahahha
However what i was talking about is something like the doc in this page which is really well done. In this way everyone could get more info about internal implementation of jME and become more and more useful to the community and maybe to the developers helping in improving the engine.
(neuroph is the first project come on my mind)
I loved jMonkey since the first day, and passed weeks reading the forums and documentations… but the website has minor ergonomical defects which can lead to understanding problems when you know nothing about jMe. Here are those I noticed :
—
The menu… choices appear when your mouse hovers over the menu. But there are a lots of people (I am one of them) who prefer to click the main choice “Documentation”, then read a sub-menu (or index) in the webpage. Sadly, there is no sub-menu in that webpage.
Suggestion :
- For every main choice of the menu (Home, Introduction, Documentation, Projects and Downloads) make sure the sub-menus are visible to the user from inside said webpage, at the top of the page.
—
Another problem I had when reading about jMoney… Projects… when I open the projects menu, I’m expecting to see external projects, mostly games, as a gallery of what jMonkey can do. BUT in there I seen jMonkeyPlatform, TerraMonkey, SpiderMonkey, Android, MonkeyZone… in my opinion, those aren’t projects, they are “Modules” included in jMonkey. This is very confusing to the beginner.
Suggestion :
- Create a “Module” sub-menu in the documentation which explains the different specialized parts of jMonkey. Excluse those from the Projects page, they are not external projects.
—
Finally, “Tutorials & Docs”, this page is very mixed up, and even now when I’m looking for an information it’s hard to find it.Tutorials for beginners, Intermediate users, Advanced users…Code samples… Installation (?) there’s already an Installation menu, why not use it ?
Suggestion :
- Do not use the word “Tutorial” since these are not tutorials IMO, they are “Starting up demonstrations”. A tutorial is supposed to guide you from a point A to point B. Those pages show you a state A and explains the code. When I started reading the doc, I was pretty lost : “where is the tutorial ?”
- Do not use the words “Intermediate users” and “Advanced users”, because you can’t do much if you don’t learn both anyway. And I was surprised when my first searches for information guided me to the advanced part… fightening ! Remember, I knew nothing about your engine and already “Advanced users doc”, this is scary
I would use something like “Guides” instead of the intermediate part, then “Documentation” for the advanced part.
—
oh, Home->Links is empty.
My two cents about this interesting topic.
The “advanced” tag is supposed to have exactly just that effect 
It is advanced and you will fail if you only read these docs because you wanna do stuff like that right now.
But I didn’t fail. They actually helped me.
Now those are just suggestions from my own experience. It’s up to you.
I labeled them “beginner - intermediate - advanced” to imply that if you have read (and understood) one section, you have progressed, and basically never need to turn back and read the lower level again (in an ideal world). First you play around with the beginner tutorials to get some hands-on-experience. Then you read the intermediate stuff to understand the bigger picture, how these smaller pieces go together. Then you start a real game of your own. Now, “advanced” questions about the details and parameters come up, and you only need to read the advanced section, which is more compact and has more dense details.
If you understood the advanced docs right away, it just means that you are experienced enough in Java to proceed fast… As we already stated elsewhere, there are people who are beginners in Java and JME; and people who are beginners in JME and experienced with Java. The latter can speed through the first parts.
The beginner tutorials show you the result first so you know what to expect. I admit that it doesn’t make the reader built it up from scratch themselves, but in the beginning it’s also important to see it work first to understand what is going on.
I asked a “neutral” friend to review the “finding out about jme” experience. He also reported he was confused about the .org versus the .com page. He understood that the .org page is a blog for community members, but since it was the first page he landed on, he didn’t find what he was looking for, the .com page would have been better for him.
When I google for “jmonkey”, I find .com (“jMonkeyEngine 3.0 - Java OpenGL Game Engine”) and .org (“jMonkeyEngine Community”). I thought it was quite clear that you would want to go to the engine first (Google at least also shows “SDK - Webstart - Engine - Showcase” in the description), and later to the community… But aparently we need to crosslink them better.
Next to the blog is “Logon”, “Download”, “About Us”, for a community blog, we would not want to prioritize these items differently… Above, in the menu, the introduction page should be pretty clear. I don’t really want to make the community hub more busy… Hmmm…
New to 3d game dev, and after having used JME3 for several weeks, my biggest issues with the docs are…
- Put dates on the wiki pages!
The number of times I’ve read and digested information only to find it’s 2 years out of date… grrr!
- Make the search DDL at the top of the page search both Wiki AND Forums, and make the selection & keyword stick between page requests.
I often find it’s easier to use Google to search for information on JME3 because of this. Of course, I frequently land on out-of-date pages, which is the reason for request #1 above.
- Drop the attitude.
Being told “I’m not going to tell you because it’s easy” or “perhaps you should just imagine your game instead of writing it” in response to perfectly reasonable beginner questions is worse than useless. In fact, a lot of the time it seems more effort went into writing a gleefully condescending quip than it would have taken to write a short, helpful answer, which kind of indicates it’s not a matter of not having the time. No response at all would be better than an insulting non-answer… and a lot less effort on your part!
I assume the tone of some of the “help” provided in the forums is because you’re sick of people asking questions without having read the documentation (which I’m sure is frequently the case, and understandably frustrating). But, you seem to have lost sight of the fact that the concepts may seem obvious and the documentation easily-accessible to someone who is already familiar the ins-and-outs of JME and 3d Game dev. However, for beginners coming to grips with the SDK & 3D in general, the learning curve is ENORMOUS, and even after spending hours reading disparate snatches of info spread across docs, tutes, javadocs, wiki pages, forums, etc. (a lot of it out-of-date), teasing out the “obvious” information is not such a simple a task… especially when you don’t know what you’re looking for up-front, hence don’t know where to start looking for the answer!
So, some of the attitude I feel is often misdirected, and extremely off-putting to people who are genuinely trying their hardest to understand your SDK. Also, it looks terribly unprofessional, which I gather is not the image you want to present, and it undermines all the hard work that has obviously been put into developing this wonderful SDK.
Anyway, you asked how to help beginners, and that’s my 2 cents worth. Take it or leave it.
@jonmonkey said:
New to 3d game dev, and after having used JME3 for several weeks, my biggest issues with the docs are...
1. Put dates on the wiki pages!
The number of times I've read and digested information only to find it's 2 years out of date.. grrr!
This is a good idea. I think we have a lot of crufty stuff in the corners and anyway it's nice to see what has been updated to the latest versions. I don't know if there is an automatic way, though... would be nice.
@jonmonkey said:
2. Make the search DDL at the top of the page search both Wiki AND Forums, and make the selection & keyword stick between page requests.
I often find it's easier to use Google to search for information on JME3 because of this. Of course, I frequently land on out-of-date pages, which is the reason for request #1 above.
I almost think we should remove the search box in the very top. It's next to useless for searching the forums. The custom google search just below it is better... though it seems to pull up links from the test site for me sometimes. The info is still good but you can't paste the links to help people without reworking them. Really, I agree here that either way searching is kind of hit or miss.
@jonmonkey said:
3. Drop the attitude.
Being told "I'm not going to tell you because it's easy" or "perhaps you should just imagine your game instead of writing it" in response to perfectly reasonable beginner questions is worse than useless. In fact, a lot of the time it seems more effort went into writing a gleefully condescending quip than it would have taken to write a short, helpful answer, which kind of indicates it's not a matter of not having the time. No response at all would be better than an insulting non-answer... and a lot less effort on your part!
I assume the tone of some of the "help" provided in the forums is because you're sick of people asking questions without having read the documentation (which I'm sure is frequently the case, and understandably frustrating). But, you seem to have lost sight of the fact that the concepts may seem obvious and the documentation easily-accessible to someone who is already familiar the ins-and-outs of JME and 3d Game dev. However, for beginners coming to grips with the SDK & 3D in general, the learning curve is ENORMOUS, and even after spending hours reading disparate snatches of info spread across docs, tutes, javadocs, wiki pages, forums, etc. (a lot of it out-of-date), teasing out the "obvious" information is not such a simple a task... especially when you don't know what you're looking for up-front, hence don't know where to start looking for the answer!
So, some of the attitude I feel is often misdirected, and extremely off-putting to people who are genuinely trying their hardest to understand your SDK. Also, it looks terribly unprofessional, which I gather is not the image you want to present, and it undermines all the hard work that has obviously been put into developing this wonderful SDK.
Anyway, you asked how to help beginners, and that's my 2 cents worth. Take it or leave it. ;)
There are a few different kinds of beginner. We get everything from the beginners who just picked up Java because they saw some cool game and wanted to write their own... all the way to the guys who read the docs and two days later can already answer questions on the forum.
3D graphics is a HUGE subject to take up from scratch. Java programming is a HUGE subject to take up from scratch. Game programming is a HUGE subject to take up from scratch. It is nearly impossible to start all three and expect to be productive right away... especially if the person starting completely skips the tutorials. (And if you already know Java and 3D graphics then JME takes only an hour or so to come up to speed on.)
It is frustrating and it does jade those who help a bit. It's hard to get asked the same questions for the 50th straight time... especially when they are already in the tutorials or when they are basic Java questions. I'm certainly guilty of being pretty dismissive of those who don't even know how to write two classes in Java.
I actually think one mistake we make is not putting a giant 48 point red message at the beginning of running the SDK that says "You must know Java reasonably well to continue." Though we have empirical proof that most don't read that stuff.
I'm old and curmudgeonly but I think it's impossible to literally start from square one in all of these areas at the same time. So perhaps what is needed is to define what "beginner" we mean when saying beginner and then state that clearly.
It’s hard to get asked the same questions for the 50th straight time… especially when they are already in the tutorials or when they are basic Java questions..... we have empirical proof that most don’t read that stuff.
I totally get that! And I think I'd become frustrated too at being asked questions by someone who obviously hadn't put any effort into finding out the answers first themselves.
I just felt compelled to relate to you that my own experience of learning JME & 3D is made a lot harder because I'm often too frightened to post a question - even after having spent hours (sometimes days!) trying to understand the concepts involved. Or, if the question is "answered" but not to my satisfaction or understanding, I'm too frightened to say so, and go away none the wiser for having asked. This is resulting in extra-long development time for things which I suspect could be cleared up quickly with a bit of expert knowledge!
Now, having said all that I realise my attitude here could come across as more than little ungrateful (given that all this stuff is provided for free, works fantastically, and is obviously the result of a great deal of time & effort from you guys) but let me reiterate how much I appreciate that JME exists at all, and that you have an active forum in which questions are being answered (if you know the right questions to ask), and that I do understand the level of frustration
So perhaps what is needed is to define what “beginner” we mean when saying beginner and then state that clearly.
Indeed. Also, perhaps a forum specifically for beginner questions might be a good idea? A collection of all those questions that are asked repeatedly, together in one place might reduce their incidence, and also you'd know the level of question before you bother reading the post to answer (fore-warned that it likely to be a "dumb question") Be gentle in the beginner forum, but if it's a dumb question posed in another forum, well.. then let 'em have it. (!)
I think we're all trying to make this work, and I'm sure it's in everyone's interests to have as many finished games as possible to showcase the SDK. So I guess I'll just plow on (my "killer app" is finally taking shape nicely, by the way! :) ) ask more questions more frequently, and hang the consequences of asking "dumb" questions and being talked to like a child. ;)
Cheero!
I’ve done computer troubleshooting for so many years that I don’t want to say for how long. But, 90% of the time when they’re into trouble, when you asked what they did, you’d get “Nothing! It happened by itself!” or variations. Or, the “fixed it themselves”, and you’re the one having to pick up the pieces. What I’m saying is that people lie. The do so constantly and unashamedly. They’d rather blame someone else than man up and admit they foobared.
It’s a similar situation here. They’ll whine and post and post and at one point you decide that it’s enough. Even though you try to explain, tell them they’re doing it wrong; it’s not true, it’s the doc, it’s you who misunderstand, it’s their dog/cat/guinea pig’s fault. Because they didn’t understand they’re blaming you too, but still insist you paste the code for them.
When I came over here a year ago I hadn’t done any game programming at all, I was -starting- Java, but I have a programmer/analyst diploma. The problem was, I hadn’t programmed (not any real programming anyway) for close to 15 years. I think in the first 6 months I posted 10 times, if that. My point is, I’m here for the long run (Yeah, you won’t get rid of me that easily!) and I -do- want to learn and eventually release that damn game. Many posters here are barely sight-seeing. A lot of them are ADDs (nothing wrong with that) and/or are too immature to stick to it. Instant gratification is -not- found in programming. Oh no. That is unless you steal code, but that’s a different story.
I honestly couldn’t tell you what’s the ratio of whiner to people who make efforts, -real- effort. But there’s no foolproof way of knowing either way unless you take the time to discuss. The thing is, we all have our lives and even though I love spending time here, I’d rather code than type code/help someone when there’s 50 gazillion thread on the subject already.
Most programmers (and also others) are curious people that like to learn stuff, do stuff and share it. If people come here thinking they’ll get rich by next week making a game because it’s Java while making the next “Minecraft” they’ll have a rude awakening. Besides, most people who tried that have abandoned a long time ago, although we do see a new one once in a while.
Anyway. When I can I try to help, but I -hate- losing my time.
Sorry for being long-winded.