On 1/6/07, Mark Ramm <[EMAIL PROTECTED]> wrote:
> > Go for it! But remember that ToscaWidgets will become the standard. > > I know. That's what's so fascinating about TurboGears. We don't really need > documentation, because before you'll get to know a component properly, it'll be > replaced by another anyway ;-) Buwahahaha! You've figured out our dastardly plan ;) But seriously, I think Jeorge's comment is useful in that we should also look to the future. That said, I think spending time working on good Widget Docs for 1.0 is very worthwhile! For one thing, good Widget Docs will give us something to work from when documenting ToscaWidgets -- they really are pretty similar (on purpose!!). And if you think the documentation of TurboGears Widgets isn't good, you'll really not like the ToscaWidgets documentation situation right now. ;) Beyond that, I doubt that TurboGears 2.0 will be released all that soon, so 1.0's shelf life will definitely be long enough that documentaiton will be worthwhile, not to mention the fact that some people won't migrate tu TG 2.0 right away, so 1.0 applications will be out in the wild for a long time. So I think documenting TG 1.0 is a remarkably worthwhile project. If I didn't think documenting 1.0 was worthwhile, I wouldn't have wasted all my free time for 6 months writing about it;) Seriously though, Karl has done an amazing job with the online docs in the last couple of months, and I think if we get together and work on it we can have some of the most amazing online docs of any web framework. We have the infrastructure, (except the automatic API doc generation) and we have the talent, we just need people willing to chip in and help. --Mark Ramm
Perhaps a change in philosophy going forward will assist in keeping the documentation complete. Documentation is not something that is done after code has been accepted it should be considered a part of the code just like the BSD's do, missing or incomplete documentation is considered a bug. The hacking part of the manual talks about epydoc (which is good) but it doesn't specify that all input/output be documented -- nor does it specify the use of __doc__ strings in enough detail to make things consistent between two developers / documenters. Is there a documentation czar in the TG project? Someone with enough sway to make sure documentation is ready before the thing is blessed by TG? -j --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
