[Twisted-Python] Twisted Euphrates (Modified by Glyph Lefkowitz)

[Mary Gardiner]

My concern is entirely documentation, so forgive me for glossing over
every other detail contained in your post.

On Tue, Mar 23, 2004, Glyph Lefkowitz wrote:
> As part of this process we hope to improve the website to reflect the
> name "Twisted" as primarily a part of "Twisted Matrix Labs", the group
> of developers working on these projects.  Similar to tigris.org, TML
> is "a mid-sized open source community focused on building better tools
> for networked application development".  Package maintainers: each
> project should have its own sub-site, so consider a project
> description and any other documentation you might want on that site.

I'm not sure what this implies for the documentation: there isn't a very
clear distinction drawn in your post between API documentation and
HOWTOs -- perhaps this is as it should be but there are some
distinctions for this exercise.

It seems fairly uncontroversial to me that API documentation gets split
off onto the project subsites, especially since this can be automated.

The situation with HOWTOs and other documentation is less clear. The
"Twisted documentation project" already has its own separate section of
the repository, but there are few internal distinctions between Twisted
Web docs and PB docs (for example) aside from in the HOWTO index.

Interface changes to one Twisted project would require a partial HOWTO
release, which suggests that the HOWTOs should be split as well.

However, splitting the HOWTOs into the separate projects leaves the
question of any docs that cover the entire family of projects: the
tutorial is the single best example. There are also documents that are
relevant for developers using many of the products, the documentation on
asynchrony is an example. It also leaves open the question of
responsibility for keeping those docs up to date.

As for me personally, it's unclear whether this leaves my role as
documentation editor redundant or not. Certainly, maintaining documents,
or coordinating the maintainence thereof, for a whole bunch of projects
on a whole bunch of release cycles is a different, and probably bigger,
task than maintaining one set of documents for one project. Even the
latter task is only notionally mine (the time I can devote to Twisted
documentation is only around 5 hours a week).

If decisions are made affecting this, please let me know. I'm willing to
provide input if you like, but I'm not often on IRC, that powerhouse of
Twisted decision-making.

-Mary