This is fantastic feedback. I've only had a little bit of time to go over your notes, but they all seem to point to areas where we can improve things without too much work.
I'm planning to dive into the online Docs next weekend, so perhaps this will be a good starting point for me to work through some stuff. --Mark On 10/15/06, chiangf <[EMAIL PROTECTED]> wrote: > > >From a request of a friend that contributed code to TurboGears, I kept > notes from when I started looking at TurboGears until I understood the > basics. Just a quick word about my background. Most of my experience > lies with Java and some Perl. Before last week, I did not know > anything about Python besides the name. I browsed through Python > basics using "Dive into Python" > (http://diveintopython.org/toc/index.html) so I'm not claiming to be an > expert or even to be familiar with Python > > The following is the compilation of my notes: > > > Setup > > * was a little hard to determine which determine which file to > download... the main page says tgsetup.py, but windows installation > page http://docs.turbogears.org/1.0/InstallWindows says ez_setup.py... > i tried the former but it didnt quite work (probably because i did it > wrong) so then i tried the latter method, which worked... a little > confusing with two different methods > > > Brian's TurboGears Tutorial (http://docs.turbogears.org/1.0/TodoList) > > * when going through Brian's TurboGears Tutorial, i think it might > be a little out of date, because during the first few steps, it asked > me Do you need identity (username/passwords) in this project?", which > was not covered in the tutorial > * for MySQL you need to set a length for email in the User class > (dont know if this applies for SQLite) > * What's the difference between UnicodeCol and StringCol? > * "In addition, each user should have their own resource in the > Userscontroller"... i had no idea what he meant by "resource" until i > kept reading... i wish that what we were trying to do was explained > briefly... also, it would be nice if the code was commented > * I find it strange sometimes when after i make changes, the > changes appear at localhost:8080 (the server automatically restarts > after i save)... but then other times, even though it automatically > restarts, i still need to manually shut down and then restart... im not > sure if this is a consistent thing, but i noticed it for the template > tutorial > * i also had no idea what templates were when i started > * i dont know if this is possible but having links to python docs > for built-in functions would be nice because ppl (me) tend to forget > things rather quickly what they do > * while trying the form handling tutorial, i get the error > TypeError: decoding Unicode is not supported... i fixed it with email = > email.encode('utf-8') > * doesnt say what cherrypy.HTTPRedirect does and how does this > differ from redirect() used in 20min screencast? > * should have a link to mochikit docs... i had no idea where > getElementsByTagAndClassName() came from until i found Mochikit docs > myself > * between editItem and saveItem, it would be better with more > descriptions... it is not clear what field[0..2] is referring to > anymore in saveItem, especially if one isnt quite thinking > * i dont think its clear where var showChanges = function(editBox, > button, data) {...} gets its 3 parameters since its simply sent through > like d.addCallback(showChanges, editBox, button);... in fact, even > after reading mochikit docs, im still unsure but i think its because > its chained > * at the end of Brian's tutorial, it mentioned advanced topics > about TurboGears, which i wish was in another tutorial > > > 20min Screencast (http://docs.turbogears.org/1.0/Wiki20/Page1) > > * while watching the screencast, i had no idea where publish_parts > came from... after perusing and googling, it was still difficult to see > a decent example... i learn best with examples, not descriptions... > compared to java, java api has much more concrete examples than python > docs... otherwise, python is definitely much more elegant and easy to > learn > * <div py:replace="XML(data)"> should have some explanation as to > what XML does, or have a link that points to an API somewhere > * in case people dont want to try it out themselves, it might be > helpful to include screenshots or perhaps a working tutorial site of > what the page would look like after each addition in the written 20-min > wiki tutorial (because the screencast would take too long to see)... > for example, after watching the screencast, i now look at the written > tutorial, but i dont want to actually program it, so screenshots would > have been useful for me > * the written example explained a bit more of what publish_parts > was but the explanation itself was difficult to find... also, it still > doesnt explain exactly what it does and why we need it to grab html > data from the database > * which reminds me... @expose was not explained in either > tutorial... but i can guess what it does... still would be nice to be > explained in detail though > * a finished source code available for download (controllers.py, > models.py, templates, etc.) would have been useful for those that have > watched the screencast and do not want to program it but still want to > test it out > * the first tutorial did things somewhat differerently (im thinking > of the redirects) than in this tutorial... im not sure what the > difference is, if any... cherrpy.HTTPredirect vs. turbogears.redirect? > > > Overall > > * more explanation of the 3rd party functions (and perhaps links) > * API needed... difficult to program without it > * include concrete examples and results (what the examples will > produce) in the API, if possible, otherwise it will be as confusing as > the 3rd party docs > * screenshots > * inconsistencies between the two tutorials? e.g. redirect > * i know that this isn't up to TurboGears, but web hosting options > is really important to casual users such as myself as well as > pricing... i know that i can get a PHP host for $5-7/month but a Python > host are less popular and TurboGears hosts are even fewer in number and > in order to sign up with WebFaction, I need to pay $4-5 more/month > > > > Continuing the last point in "Overall"... in the > http://www.turbogears.org/docs/deployment/hosting.html page, under > WestHost... it says that TurboGears can be run under "straight > proxying". What does that mean? > > > > > -- Mark Ramm-Christensen email: mark at compoundthinking dot com blog: www.compoundthinking.com/blog --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/turbogears -~----------~----~----~----~------~----~------~--~---
