First, let me apologize for my absence. Before I could reply to this, I got sucked into a difficult piece of code at work, and just crawled out of it today.
On Thu, Jul 15, 2010 at 12:40 AM, Guyren G Howe <[email protected]> wrote: > I should say that I'm impressed by those parts of TurboGears that I > understand. It can be forgiven that I'm frustrated by things that I don't, I > hope. :-) > We have quite a few gaps in our documentation. I need to write up a pair of extensions (in addition to completing some changes to a third one, tgext.menu), and then I'll be back to cleaning up the docs. > Certainly not, but on the other hand, you and no-one else has said not to. > It doesn't take much reading about TurboGears to learn that the project is > about integrating other projects. I started out trying to follow the TG > docs, and when I ran into trouble trying to make things work with those, I > figured — and it indeed appears to be the case — that there would be more > details about the individual parts that are integrated in TG, in the > documentation for those separate projects. > I submit that this is a pretty reasonable way for me to have reasoned. If > there are caveats that should have applied to this line, I didn't see them, > and it would be useful to add them, prominently, in the introductory > material. > It is, and I've just added notes to remind myself to add those sorts of notes. Sorry if I gave the impression of Railing, I was just discussing things from > the perspective of what I know, which is Rails. There are things here > (routes) that appear to let me do what I am used to, only *they didn't work > for me, and still don't*, even though they appear to be very simple and > basic. > > I am okay with leaving that issue aside since apparently I'm not doing > things the idiosyncratic way, but if it's not idiosyncratic TG to implement > a restful api using routes, the docs on routes should say so, is all I'm > saying about that. And I'm still wondering why that level of abstraction — > separating the routes from the api calls they map to by default — isn't seen > as either necessary or at least desirable. Is it because if I decide to > rewrite my controllers without changing my routes, I can add routing later, > and using Object Dispatch is simpler until then? That's the only answer I > can imagine, and I think it deserves a comment somewhere in the docs. A lot > of people are going to come from Rails or one of the now many Rails-inspired > frameworks, and go looking immediately for how to set up routes. > I can see where you're coming from with this. In TG, we use Object Dispatch by default. Honestly, I've never used routes myself, and I really don't have any desire to do so. I look at Object Dispatch, and say "This makes sense to me." I like it. So, when it comes to telling me anything about routes, I'm going to have to take your word for it. For my money, using Object Dispatch is extremely easy. I start by looking at the page I need to update (for whatever reason). Now, where do I find the end file I need to update? Open root.py, look at the RootController. Find the next URL segment. Using this, I can drill down as far as needed quite easily. My code maps to my URLs in a way that's easy for even a new developer to dig into. From what I've heard of routes, this doesn't seem to be quite as true. I could be wrong, though. > A "TG for Rails developers" would be exceedingly useful in this kind of > regard. > I'll happily write one once I'm more familiar with TG. In fact, I've done > more than my fair share of technical writing in my time, and I'll happily > contribute to the docs, if you can help me get to the point where I > understand things. :-) > Indeed, it would. It's one of the things I would like to see, personally. Please do feel free to contact me using IM. My addresses are in my sig. If I'm in the middle of something hairy at work, that's the approach that's most likely to get me. > Sure. Again, I greatly appreciate you taking the time to write all this. I > hope this interchange can be genuinely helpful in improving the docs. > Believe me, I understand how much work it takes to produce documentation. My > impression is only that you don't have the resources to be as thorough as I > would love (I'm sure you would love, too — we all want everything now, > right?). I should say finally that the docs for TG that are there are of a > very high standard. There can always be more docs and more refinements, > right? :-) > One of the last big pushes I managed to get done with the docs was to get our todo list cleaned up, working, and generated by Sphinx. Since then, I've dabbled, but not had the time to dig in. I need to make that time again, soon. -- Michael J. Pedersen My IM IDs: Jabber/[email protected], ICQ/103345809, AIM/pedermj022171 Yahoo/pedermj2002, MSN/[email protected] -- 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?hl=en.
