This is really a web page bug report more than a question

This is really a web page bug report more than a question

I just want to provide some feedback. I have been trying to get started with jquery mobile and find that the jquerymobile.com web pages do a very poor job of supporting beginners.

First let me say that jquery mobile looks like a wonderful thing. Lots of people have obviously worked very hard to make this a great tool. Some of the things I say below are probably wrong. Some things that I say don't exist probably do, just not where I expected them to be. Please don't take this as a detailed bug report. The intent is to document my experience as a beginner in a detailed way in case if gives the team ideas on how to improve things. I don't really need answers to this post. This is not a request for help. I have satisfactory answers to all my issues so far. As an experienced developer (though new to jquery and jquery mobile) I can solve my problems the hard way (web tutorials, books and just keep digging.) If I do get blocked I will post specific questions and based on what I see browsing here I will quickly get expert help. Overall this site seems very good. Beginners are a special case though and my experience suggests that this site does not do well at that particular special case. A process that would have taken me minutes if the needed info was collected in one obvious to find place ended up taking days.

I suspect the experienced users and developers of this site don't realize how beginner unfriendly the site is. The reason I am posting this is that the experience was so bad I suspect it drives away many casual beginners just exploring the possibility of using jquery mobile. I'm sure that is not the intent. You probably don't hear from most of them. I'm sure many just give up and go away. The startup cost is much higher than it should be.

I'm also sure these pages do an excellent job for more experienced developers. They seem to assume you are already javascript and jquery fluent. There are several structural issues that make it difficult to get started. For me the problems center around a key beginner problem: what should the very first jquery mobile html file that you create look like, call it a beginners template if you like. Below I mention places this should be handled but isn't.

1) Possibly the key problem is temporary and related to the transition to the new version. At the top of the main page it tells you that 1.3.0 is the latest stable release. However the "demos and documentation" link takes you to 1.2.1 documentation. I found 1.3.0 documentation with google but the website top level doesn't seem to link to it. There is no easy-to-find place with a starting template for 1.3.1. I was able to get there with bits and pieces of information found various places. (Note: By accident I just discovered a link to 1.3.0 online doc in the download page. To me that is not exactly an intuitive place to look for it. No starting template though.)

2) Structurally the site doesn't deal with versions well. They are written as if there is only one version (the current) This breaks down during transitions. There should have been 1.2.1 support pages that didn't change, in parallel with a 1.3.0 replacement. Even after 1.30 is released the 1.2.1 version of support should stay around until support for that version is eliminated. The stable version should be the default. Instead what I see is a web page structure that is version blind (except for the download pages) and is currently not consistant about it.

3)   The doc/demo methodology is to provide code fragments which typically show how to create a single <div> element tor a particular feature. They assume you already have a framework (<head> with its resources) in place that you can stick this fragment into. In other words the details are well covered but therem is almost no context documentation.

4) Obviously an important starter issue is what versions of the resource files should be used. If there is a place that says which versions of jquery resources mobile 1.3.x is compatible with I can't find it.

5) The demo pages html files give appropriate information as documentation but are not themselves useful as examples. They point to site specific resource locations (../../file...) An expert would have no problems saving these pages and editing the references appropriately but a beginner is lost. A more beginner friendly to do this would be to use cdn references in these pages

6) 1.2.1 doc has a getting started link which has a template. 1.3.0 doc seems to have lost the getting started link. I ended up taking the 1.2.1 template and editing the resources it used but see 4) above. It wasn't easy to figure out the appropriate resources 1.3.1 needs instead.

7) The "introduction" link is useless for getting started. It says "beginners start here" but it just skims key features in a summary way. Why should a beginner start there? It is likely that by the time a "beginner" gets to this point they already have an idea what jquery mobile is. What they need is "what to do next."

8) The fact that downloaded demos from the zip files require a web server (php) is not beginner friendly. Setting up a server is just one more hurdle for beginner to overcome.

An ideal demo page for a beginner would have a link to a standalone file which could be downloaded and immediately edited and then viewed in a browser. This site does not provide that.

I am beyond this stage and I wish to thank all the developers/volunteers for a great tool that I'm finally beginning to explore. I posted this to hopefully benefit future newbies coming to jquery mobile.

-steve