I think we need a bit more organized effort here. For instance someone can take a lead on docs. He could create a TOC of a manual/wiki, and then we can individually pick sections to fill in the doc/wiki, i.e. be a contributor. Point being there has to be someone constantly looking at it and adding sections, alerting contributors of new features to be worked on. Also, the same doc/wiki would be the place when a new feature is added, the feature owner/contributor writes 1. what is it; 2. how to use it? 3. background info (if any) etc.
Since I am not well versed with web2py end-to-end, I am not the best person to take up the leading task, but would definitely want to be a contributor. On Feb 24, 6:37 am, Iceberg <iceb...@21cn.com> wrote: > +1 for improving documents, of course. > > I am not sure what Achipa means about changelog, but I believe the > developer of a new feature is the most appropriate person to write > some description about: > 1. what is it; > 2. how to use it? > 3. background info (if any) > I am afraid that changelog can not contain that much information. > > Actually, most kindly buddies already wrote some decent docs. The > recent two examples I knew is Massimo's excellent doc about the new > tools: > http://mdp.cti.depaul.edu/examples/default/tools > and Achipa gave enough information about the cron patch here: > http://groups.google.com/group/web2py/browse_frm/thread/44817da72c798df8 > > The point is that, we need one, and only one, "central" place to > contain ALL the info. > To me, there is no better place like the build-in "example" > application (or the latest one > here:http://mdp.cti.depaul.edu/examples/default/docs > ). > > Perhaps, the developer of a new feature should also describe that > feature in his local web2py's applications/examples/views/default/ > thefeature.html, then provide this file to Massimo so that Massimo can > include it in the next release. In this way, we all share the load of > document from Massimo. > > On Feb24, 6:07pm, AchipA <attila.cs...@gmail.com> wrote: > > > +1. My suggestion is to have an as detailed as possible changelog when > > a new version is released. This is a lot of time, admittedly, but > > would allow for people who do not enjoy spending the whole day in the > > gluon dir to integrate these detailed changelogs into the actual docs > > and take some load off Massimo wrt to docs. Sooner or later most OSS > > projects come to the point where they need to appoint someone to be in > > charge of docs as usually the core developers are more keen on coding > > than formatting docs or making examples. I don't know if we are just > > near or have already crossed that point :) > > > On Feb 24, 10:15 am, Joe Barnhart <joe.barnh...@gmail.com> wrote: > > > > It seems to me that we have reached a critical point in web2py. > > > > The development of web2py has been at such an accelerated pace that > > > the environment has far outpaced its pool of documentation and > > > examples. I am using the latest stable version and loving the new > > > capabilities of "auth" and "crud", but I find I'm spending an > > > increasing amount of time in the gluon directory, trying to read and > > > understand the source. > > > > Maissmo's web2py book is an excellent starting point, and it got me > > > through the basics and well into my first web2py site. But there is > > > so much to learn -- so many ways of solving the common problems that > > > surface again and again. I look to the wiki and the mailing list, but > > > the answers just aren't there, or are so diffuse that it's hard to > > > find them. > > > > This is a critical point because we have the chance to make web2py > > > "mainstream", but only if we can get the information flowing at a pace > > > equivalent to development. Documenting is not as fun as development. > > > But if users must read the source to understand how to create sites, > > > we will never turn the corner and make web2py the success it could be. > > > > From where I sit, documentation and examples are the #1 problem faced > > > by web2py today. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "web2py Web Framework" group. To post to this group, send email to web2py@googlegroups.com To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/web2py?hl=en -~----------~----~----~----~------~----~------~--~---
