[Twisted-web] Thoughts on documentation, wading into Twisted, Nevow, etc.

[Valentino Volonghi aka Dialtone]

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 <terry at jon.es> 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 :)