The others already answered to your email and they basically all said things I
agree with, hence I'll concentrate on proposing yet another way of trying to
solve this problem. :)
On Mon, 3 Jul 2006 03:15:32 +0200, Terry Jones <[EMAIL PROTECTED]> wrote:
But, if you think there is a problem, what can we do? Here are some
possible concrete steps that wouldn't take huge amounts of time.
1) Go through all Twisted & friends web sites and wiki and _ruthlessly
delete everything_ that mentions obsolete, deprecated, or renamed
projects / modules, broken links, example code using such, etc. There
are many of these things, and they are highly misleading and
frustrating and give a bad overall impression.
I agree on this but only when we will finally have a completed twisted.web2
that will allow us to port Nevow to it. Some effors are already going in this
direction with the recent #1252 bug in Divmod trac and the no-more-context-1252
branch.
Given the relative simplicity of this newly written code it might be a good way
to start looking at Nevow and writing some documentation with developers' aid.
I'll have the last exam of this university year on the 5th, after that day I'll
probably have plenty of spare time to develop and help documenting Nevow. Not
being a:
1) Native english speaker
and
2) Good at explaining things clearly
I wouldn't be the right person for documenting Nevow in first person while I'd
_love_ to help somebody else to write new documentation (by reviewing,
answering, completing and whatnot).
I also have some applications under the MIT license that show how to use Nevow
mechanism outside Divmod infrastructure (which despite being really well
written is not always the best solution for any problem, like they know well
enough :)) and the code can be taken as an example or best practice or just a
starting point.
2) State, where appropriate, that the source code is currently the best
documentation. There's no shame in this, and it's much better than
having people run across and waste time on obsolete docs, or spend time
looking for things that do not exist. E.g., "At this point the
nevow.url class is totally undocumented. See examples/{x,y,z} for
example usage and the code and comments in nevow/url.py for the best
current documentation."
Sometimes the Nevow source code is not really clean and cannot really be
understood (the url module is a good example of being mildly obscurish) however
it's much better to redirect to it than to provide outdated documentation, this
is an unfortunate problem that has plagued nevow since long long ago and nobody
bothered fixing because we literally have no time :(.
4) Have someone go through example code to stick in more comments, get rid
of old stuff (no need to rewrite if that takes too long, just throw it
away). E.g., the widespread use of formless in Nevow examples. Is it
in, is it out? If the latter, get rid of it before more people die.
Another thing I agree with. IMHO it's been a while that formless has been more
or less discontinued and it should at least be definately separated from nevow
if not just dropped. There's also an additional problem to this since currently
there are 2 different form libraries one that integrates with athena and
another one that does not. formal and liveform.
Also in its current shape formless is not even close to being what it was
thought for, I know many use formless currently for their needs but IMHO (and I
would like some opinions on this of course) having 3 form projects of which 2
(despite being different) solve the same problem is a waste of resources.
Anyone that is spending time and effort on fixing/extending formless should
move to formal which is considerably easier and cleaner in its design also it
is fairly easy to extend. Yes it doesn't still support form customization but
adding it is not a 10 month effort because the rendering class is completely
separated from the rest and it could be added with an afternoon of work.
Allowing this would have _many_ positive effects to Nevow. For example rend.py would finally be cleaned up from the code depending on formless, faster startup for less component registration, less code in rend.py, less code in Nevow, no more CARRYOVER and so on.
Thanks for your mail :)
_______________________________________________
Twisted-web mailing list
[email protected]
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
