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

[Adrian Perez]

On Sun, 2 Jul 2006 23:44:51 -0400
glyph at divmod.com wrote:

> Thanks, Terry, for writing about this.  I agree with most everything
> JP said.

I've also found Terry's email quite interesting. I started learning to
use Nevow lately --even not mastering it in depth I find it amazingly
elegant-- and I noticed about some of the problems described. I'm happy
because such a controversial email seems being taken seroiously instead
of provoking a flame.

> On Sun, 2 Jul 2006 22:50:14 -0400, Jean-Paul Calderone
> <exarkun at divmod.com> wrote:
> 
> >Hidden (or not so hidden) here is one of Twisted's biggest problems
> >right now.  Twisted's developer base is incredibly small,
> >particularly when considering the scope it encompasses.  Over half
> >of Twisted was developed by just four people.  With twisted.pb and
> >twisted.web2 one might think that the load has been spread out a bit
> >more, but other factors have combined to result in the opposite:
> >over the last year almost 3/5ths of Twisted code has been written by
> >only three people.  That's a huge amount of effort by an amazingly
> >small team.
> 
> There is another unfortunate truth hidden (or not so hidden) here.
> 
> Fundamentally, while we'd also like this situation to change, someone
> will have to take responsibility for it.  As JP mentions here, the
> current maintainers are all overstretched in a number of different
> directions.  While all open source projects could use more
> contributions, by my estimation Twisted is something like 10x as
> overstretched as any other project.
> 
> While certain things you've suggested seem like useful stopgaps -- I
> particularly like the idea of mentioning repeatedly in the
> documentation that users should consult the source for the most
> up-to-date information [...]

At first I tried searching for documentation, but I had to step through
the code some times. Telling users not to be afraid of reading the code
would avoid people wasting their time surfing the net.

> [...] the real solution to this problem _requires_ a dedicated
> documentation maintainer for each project. That means not just a few
> hours here and there to fix bugs, but a consistent commitment from
> someone [...]

I also agree with you here. Based on my own experience, one person
may take care of the code _and_ the documentation when a project is
small, but when things start growing he/she will find frustating being
the only one taking care of documentation and will focus on code
instead.

> Terry, perhaps you would like to volunteer to be Nevow's
> documentation maintainer; or perhaps you know someone you could
> encourage to fill that role.  Without such a person though, I doubt
> that we are realistically going to have enough bandwidth with our
> existing team to even apply your simple suggestions.

I would like to help, but I don't feel like I could manage being the
main maintainer and I also like coding more than writing documentation.
Even so, if someone decides to takes care of the task, I could find
some spare time to contribute.

I know I am a newcomer here, but those are my two cents.

Cheers,

-- 
Adrian Perez
"Experience is what you get when you don't get what you want"
                                           -- (Dan Stanford)



-- 
Adrian Perez
"Experience is what you get when you don't get what you want"
                                           -- (Dan Stanford)