Yes, of course, I wasn't thinking about changelog in terms of format, but content (snippets which others can base their doc work on). The trouble with coders writing their own docs is that what might be obvious to the author isn't to the public. Also, different people have different styles, docs require a better command of english than coding, etc, etc. That's why there is often a doc master (janitor, tech writer, whatever), who knows the project well, understands both users and coders and has a good tech writing inclination.
On Feb 24, 12:37 pm, 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 -~----------~----~----~----~------~----~------~--~---
