First of all - this isn't a hate-fest. This is constructive feedback on the way Sencha Cmd has been delivered the public in a drive to make it better. Hopefully any bumps this gets will follow that ethos.
A large number of the Sencha Cmd questions on these forums & Google should already have been answered by the docs, which is evidence that the docs need a look-over by someone who's not familiar with the tech.
Vital information should never be in a footnote
See this example:
I was trying to find out why dynamic loading was enabled in my output and I came across a Stack Overflow post where someone posted a command mentioning bootstrap.js.
"What is this?" I thought. So I headed back to the Sencha docs and started reading a section entitled "Generating a Custom Bootstrap" as it looked relevant.
After reading the section, I tried to work out why this line existed:
This file gives the framework the same level of awareness of your application code that it has of the framework code itself
That sounds like something every app will need, so why do I have to manually enable it?!
I then continued reading through more revelations before coming to this point:
Note. This part is also handled automatically for applications generated by Sencha Cmd
This was about halfway down the page.
Try and get your head around this.
The disclaimer explaining who needs to read the content was halfway down the page.
Why is dynamic loading enabled?
Why is dynamic loading allowed to happen in a the compiled app? I already have a version of the app that dynamically loads classes - it's my dev version.
If the compiled app needs to look on the file system for a class then it's not a compiled app.
Why does the bootstrap file even exist?
It seems like this bootstrap file should just be taken care of by the compiler (If it's even needed). I've read the section on bootstrapping through multiple times and still can't work out why I should know about it.
Why would I be generating my own meta data?
Again, this should clearly be happening automatically as part of the compile. The way the docs on this are structured, it sounds like unless I run the commands to generate various pieces of the meta package then my app won't have them.
Is this correct? If this is vital (which is the impression given by the docs) then why is it not mentioned in the compile "walk-through",
An honest suggestion.
1. Have one guide for people who follow the Sencha best-practices for application structure and one for those that don't. Have them clearly separated and marked as such.
2. Make it as simple as possible to call the compile command:
Of course the way I think we were all expecting it to work was having the compiler take care of the manifest itself by using the dependency tree, instead of having the developer tell the compiler which folders in needs to run through - completely eliminating the need to manually exclude anything.
3. Summarise the instructions in a nifty numbered list... like this one.
4. Get someone who works with print publications to go over the docs.
@Sencha - Please respond to this. I'm far from being the only one having these problems.
@Everyone Else - Contribute, Bump and Spread ^_^
Last edited by lsdriscoll; 25 Jan 2013 at 4:47 AM.