[Twisted-Python] On splitting Twisted into subprojects

[Mary Gardiner]

On Sat, Apr 17, 2004, Christopher Armstrong wrote:
> Mary wants the documentation to be kept in a single project. I don't 
> think this is how it should be done; we'll allow each project to keep 
> its own doc/ directory. Each project should be responsible for its own 
> documentation, but I can personally ensure that you have access to the 
> docs for all the projects, though, Mary. :-)
> 
> HOWEVER, don't worry that the documentation will become disparate in any 
> user-visible sense. All projects will have their documentation visible 
> somewhere within twistedmatrix.com/, and we could even have a monolithic 
> "docs" section that links to all the others if we find it becomes 
> necessary (I think the current 'howto' page is an absolute mess, though).

Yeah the howto page is a mess (*and* misnamed as Glyph points out
elsewhere). There's also very weird coverage in places (detailed things
covered, basic things missing) that having subprojects may help with,
because coverage of their subproject will be important to them.

Goodness knows what happens to the tutorial in this model. It could
perhaps split into pieces and be greatly expanded by each subproject. It
definitely is useful to people: most docs bugs are filed against it.

At a lower level, all I really want from the docs is two things:

 1. Ability to find them in some kind of defined spot and to be able to
 edit the etc. You state this above.
 
 2. Some kind of policy about certain things which I can't even begin to
 define yet, but which may include directory structure, referencing and
 the like. However, since doc refactors are easier than code refactors,
 I'm happy to make policy when required rather than do it in advance.

 3. Cooperation from subproject developers: ie ability to hassle them
 about docs, nag them about broken and missing docs and that sort of
 thing. (At present, I file docs bugs against myself, that can't
 continue with X subprojects :) )

I think at the moment I don't really have 3, because a solid half of the
project's developers aren't aware that there is someone who has (however
tenuous) responsibility for the docs, especially since the twisted-web
list appeared fairly early in that process. I may be misjudging people
there.

-Mary