Most Frequently Asked Questions text needs peer review

Some of the ancients of this forum might remember that I once promised to write something to help people inexperienced with programming and/or jME decide if jME is for them, and if so, give them basic directions to get started.

Since then I have written and trashed a few such documents, because I never liked one enough to actually post it.

I'm not really sure about the text I managed to come up with this time either, but anyway, I thought I might at least put it up for peer review and see what you other folks think of it.

So here it is:

http://www.jmonkeyengine.com/wiki/doku.php?id=mfaq_-_most_frequently_asked_questions

It may very well need some help with proper wording and grammar, as I learned most of my english from books, articles and the internet.

But I'd also like to know what people think of the style of my writing - does it sound too sarcastic? Is it over complicated? Is the whole "pseudo socratic dialogue" thing just outfashioned and embarrassing?

Generally, I like the style that it's presented in.  I don't find it too sarcastic at all.  I do wish there was a bit more "content" to it regarding stuff mostly NOT related to jME - You suggest learning Java, to someone who's really just starting to program that's a pretty tall order and not a lot of help, maybe some links to Sun's site, or some book recommendations would be helpful.  Same for pick and learn an IDE - maybe explain which IDE's are well supported/integrated with jME and provide some links to get someone started.  It doesn't need to be much more than you have (this isn't Java 101 afterall) but I do think it would be much more helpful with just a bit more information.



Regarding the second item - I think you nailed the thought/discovery process perfectly -


Great, so now I know Java

Thanks for the comments! Actually I started my previous attempts with more content, and then realized that others had already created that content on the wiki. So I'll just have to find the places and link to them. That is for jME related content, of course - the basic programming and math stuff could sure do with a few external links. I was going to ask for suggestions for those links, but somehow forgot about that :smiley:

Good attempt, as christius has mentioned. I only want to add that perhaps it would be a good idea (since people reading that mfaq would most certainly bee absolute beginners) to lead readers in the direction of least resistance… for instance suggest Eclipse IDE since it is used by most devs and advanced users in the forum. Make the users use the CVS version instead of the nightly and/or release. this way we can save the trouble of typical already fixed problems. Finally, the running/deploying of applications that seem to be also a very typical question (i.e. Tests run, but my app fails with UndefinedClassException/UnsatisfiedLinkException and the like).



If we are going to spoil them, at least make it in the right direction  :stuck_out_tongue:

As someone new to Java and jME, but not to game programming in general, I found your FAQ to be quite condescending to new users. You seem to assume anyone wanting to check out jME is a naive gamer looking to make the next big FPS or MMO game. It’s true, there are plenty of these people running rampant on game development forums, but I do not think a FAQ you have stated is meant to help new users decide if jME will suit their needs is the place to put a lecture on what you feel is the best path towards 3D game development. I looked at this FAQ expecting to see a rundown of game specific features included with jME and alternative resources for features which may be incomplete or not implemented yet, instead I found a FAQ on how to become a game programmer which had nothing to do with helping me decide if jME is a good solution for my projects.



If you are interested in creating a FAQ on the path towards game development, refer to this one:

http://thegamedevspace.spaces.live.com/blog/cns!36A56195A2C35B9B!181.entry



It is incomplete, but I think the author has taken a better approach that is more useful to aspiring game developers and it might give you some ideas on how to approach your next revision.

I would say that the wiki has a lot of those resources you mention. It has a getting started guide. a TODO list, and the main page has a list of features… also, the forum has lots and lots of info…



I think the MFAQ serves some other purpose. It attempts to address those (many) users that have been spoiled by the Learn * in 21 days fad.

Thank you, inneractive, for your review/opinion!

I used to be worried about the tone of the article at first, but then I got some positive feedback about it, and disregarded my doubts. I think the FAQ-like structure of the article should help readers find the part which applies to them most.



To be honest, the very first part is meant to sound a little offensive - however not to make people who do ask questions that way feel bad about themselves, but rather to help them see the offensiveness in their own way of asking questions.  It is true, I do feel offended if people ask their questions in a way that implies that other people don't have anything else to do than helping them in realizing a project they weren't ready for to begin with.



From your elaborate response it seems that this first part of the article doesn't apply to you, so if you felt personally offended by that, I'd like to apologize but also say that you misunderstood me. I don't assume that everybody who happens to read that article is currently in the position of the people who asked the first question. But that there are people to whom that paragraph fits perfectly.

Basically, that's just why I gave the article the layout of a FAQ list - it's just the same with FAQs in my opinion. There are usually a few questions at the beginning of any FAQ that many people will find offensive if they think that answering the question implies that they don't know the answer.  But it doesn't! However should somebody come along who was just about to ask that very question, they'll find the answer, and hopefully heed the advice. And they will come, that's what's putting the F in FAQ!



The jME community is a very nice and cozy place, and I'd hate to spoil that impression by unwittingly insulting new users, but so far I only got positive feedback for the article in question, so please understand that while I take your objections very seriously, I won't dump the MFAQ right away, but rather wait if another voice chimes in and seconds your opinion.

I think MFAQ lists should be exactly that… answers to "most frequently" asked questions.  To be honest, our MFAQs seem to be from people who are new to Java development that want to get started writing games and thus need a hand in setting up things like a basic development environment, etc.  We also often get people who underestimate the complexity of trying to write a game.  I think this is exactly why you see questions answering those mindsets.  Perhaps if the MFAQ was wrapped up into a larger FAQ and subtitled "HELP, I'M COMPLETELY NEW AT THIS" or something, then people could ignore that section as appropriate?

Just to clarify, I was not personally offended by the FAQ, I just felt it was not what I expected from a FAQ that the original post said would help me decide if jME is for me. I have no problems with a FAQ put together for helping new game developers along their path. I just think there should be clarification between whether this is a "Is jME for me?" FAQ or a "How do I become a Game Programmer?" FAQ. Like I said, I see the questions you address being asked all the time, so I understand what you are trying to accomplish.



Anyway, just wanted to clear that up. I'm a Torque and TGB owner who has also played around with Python-Ogre looking to move to jME and Slick. It just so happened that this was the first FAQ I came across on the site having headed straight for the documentation forum. I should have hit the Wiki first.

Also to be clear, thanks for the perspective inneractive, if that was the first thing you came across, then I can totally see how it would look the way you said.  Maybe rolling it up into a larger FAQ as mentioned would help mitigate that some.