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

[glyph at divmod.com]

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

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 -- 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.  Ad-hoc spurts of effort from the community can be highly useful, but only if, when they arrive, there is a well-maintained list of priority-sorted tasks for the effort to be applied to; and once some work has been done, someone needs to stay around after the party to clean up the mess, make sure all the work goes into the right place in the repository and any critical gaps are filled in.

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.