> If you can draw diagrams, or convert files from wiki markup to REST, > you can make a meaningful contribution. So, the only reason not to > get involved is that you have other higher priority things to do. > And if that's the case, please don't vent your frustration at other > people who might also have other important things to do and spend less > time on documentation that you would like. >
I think that's the wrong attitude Mark and I would venture saying that it's because you invest so much of your time into TG that you don't want people walking in and telling you how bad it does in some areas. I used to feel that way with CherryPy last year and I was not listening enough to what some people would have to offer. If I look back it was more my ego than anything else. I'm not saying that this is necessarily your case Mark but it looks like it to me. That'd be understandable obviously. Steve is right however, you cannot ask your users to fill gaps that have been left opened by the core team. After all if the core team didn't do enough for the doc why a simple user should? Users do what their name says... they use the product and that's how it should be. Users may feel like contributing but to do so they must first understand the product. If I look at [1], where is the page telling me in simple words what TurboGears design is all about? I may look at [2] but the diagram there dates from the first version ever released of TG. Where do the Widgest fit into that? Or Identity? My point is that from a newbie as I am with TG I miss the entry point to the project. Where do I start? Where is the gentle introduction to the design of TG? Where is the roadmap page? (for a symmetric POV see [3]) The documentation shows how to create a model but doesn't explain what a model is nor why TG uses that concept let alone why a model is a good design practice for my application. What is the visibility of the project? Yeah writing documentation sucks most of the time. It's boring and makes any day looks dull. But it's worth the trouble. Mark you wrote the book you must know better than anyone here how much writing good documentation is just not a matter of chime in. It takes time and requires a fairly good insight of a project. Most users don't have that because there is already no entry point. Those who have actually create applications based on the product which makes the project more attractive. The value is create elsewhere. That being said TG's documentation is not all bad as you have recipes, howtos and screencasts (although I can't judge their own value or relevancy) and that's great because when people understand the big picture they usually want some hands on. If PHP has been such a success it's mainly because it's a set of libraries somehow glued together and people can get their hands on it quickly. TG is more than that, it's a framework and as any framework you need to know the follozing: * where is the entry point? => why should this product answer my needs? * what are its boundaries? => if it's a framework, there are things it can do others it can't and in any case I will have to obey the framework's rules to develop. So what are they? I need to know that upfront (it's much deeper than saying you can replace ORM X with Y... it's about the design I'll have to bend to) * what is the short, mid, long term future of the framework? Will I have to drop everything on the next version? It might be the case and that would be fine if the reasons are motivated and referenced. On a more positive note TG is not an exception, far from it, most OSS projects fail to bring the big picture and explain why they made such or such decision and what is their next goals. My personal projects fail there too but I don't have the expectation TG has. CherryPy was not much better although Robert has done a great deal in improving that situation since CP3 was released but I think we're just safer because CP aims at covering a very narrow area of web development. Even though we still have lots of questions that could be avoided if only we had better documentation (and considering I am in charge of it... it says a lot about how I feel about it). However where the CP team did succeed is by staying focused on what they had planned for the project. All along many people have requested us for features. Some were accepted and integrated others were disregarded because they didn't fit the purpose of the project. Some have judged us pretty poorly of course but you can't please everyone. You want to make TG the number one? Drop the extra features, consolidate the core and provide the best documentation you can afford about the project, on how to use it and where it goes (a roadmap goes a long way). In a nutshell I think you confuse complaining with the will to warn that maybe it's time to step back and look at what has been accomplished, where the project fails and where it succeeds. I deeply wish all the best to TG in the end nonetheless. - Sylvain [1] http://docs.turbogears.org/1.0 [2] http://www.turbogears.org/about/index.html [3] http://griddlenoise.blogspot.com/2006/03/crisis-of-faith-messengers-have-been.html --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
