gasolin wrote: > Hello: > > I just rewrite the most complained document: 'Exposing Methods to URL' > in reference section > > http://docs.turbogears.org/1.0/GettingStarted/CherryPy > > The former document introduce a lot of source code and you'd dive into > it and analyze the beauty of object mapper (it scared people). Now I > tried a more dummy (still have room to be improved) approach > > I'd like to toss three questions: > * is this more readable?
Well, because it's a Wiki that question is only meaningful to those familiar with the previous page ... I thought the code example was reasonably good, but that doesn't mean your new approach can't be better. > * any basis need to be mentioned here? I'm not sure what this question means. If you mean should you start with a short discussion of principles then I would say the answer should be "yes", because it would then be easier to see that your sample code implements the principles you have outlined. > * how to express them in doc? > There seems to be some confusion about the information that's relevant to the reader at this point. You start out by saying that "program method (Object) is mapped to URL", but actually when the server receives a request the URL needs to be mapped to a method. Discussing the mapping this way round makes it easier when you need to introduce the default() method, which has an infinite number of mapped URLs. Your first code example under "Hello TurboGears" uses the @expose decorator without its significance having been explained - by that point the reader should already understand that only exposed objects take part in the URL mapping (from your later discussion they *will* be prepared for a lot more complexity in expose() calls later on, which is good). Rather than saying "controller.py is the root of your project, in TurboGears all web pages are mapping from controller.py" I would say "The framework requires controller.py to define a Root class, which will normally be a subclass of turbogears.controller.RootController. The server creates an instance of this class to act as the controller for your site". By the way, in my site that is "controllers.py" rather than "controller.py" - am I working with an older version, or is either acceptable? I wouldn't introduce the default method in the first example - particularly not one that I suspect will only ever generate an error because it will inevitably be called with at least one positional argument. The user will then see a traceback ending with "TypeError: default() takes exactly 1 argument (2 [or 3, or 4, ...] given)". I'd hold off on discussion of default() until after you have demonstrated multi-level URL mappings. Then you can show the value of having default() at several levels. When you say "But if you access http://localhost:8080/sub/oop, you'll be redirected to the front page (http://localhost:8080)" you should follow that with " because there is no mapping for the URL, so instead the server calls Root.sub.default('oop')". You should change the default method to take a *arg argument, I believe. > And I open the permission for anyone who wants to enhance this doc.(we > have not discussed for this yet, hope other editors don't mind) > I haven't just gone in and edited the page because a) I don't have the time, and b) I'd rather help you to think about what needs improving in the writing, so you continue to improve all the documentation you write. There are small faults in the English but they really aren't significant, and can easily be copy-edited later. Try to put yourself in the position of someone who's completely new to TG and needs to understand from the ground up. Preferably, try to make each page stand alone in case the reader has just dived straight in there without reading what went before - they do that, you know! > > > FYI: I also add the project structure in The Big Picture > http://docs.turbogears.org/1.0/GettingStarted/BigPicture > Unfortunately I have never found the graphic terribly helpful in relating to the model/view/controller concept because only the model is actually shown as such in the diagram. It might be helpful to point out that it's the controller's responsibility to map URLs to actual functionality, and that such functionality will call the model's API to retrieve and/or update the data in the database, and will use some sort of templating engine to provide the user's view of the data. It might also be worth emphasizing more strongly that the controller is the basis of the framework, and that the view and the model can be created in other ways. That way people can realise they can port existing web software into TG without an immediate complete revision to all of the code. [That's what I am currently doing with the samples from "Python Web Programming", and it's surprised me how relatively small the necessary changes have been]. I hope this doesn't come across as negative criticism. It is intended to help you write better documentation, not to stop you from writing! It's great that you are producing this stuff and asking for feedback, and this is *my* attempt to maximize the return on the limited time *I* have to try and help improve the docs. Keep up the good work! regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
