[Twisted-Python] Questions about adding documentation

[Santiago Aguiar]

Reza Lotun wrote:
> Rather than change the documentation system entirely, who don't we
> just create a new resource for Twisted documentation - a Twisted
> Documentation Wiki. At the very least it can be a repository of
> various tips and tricks we happen to find, and maybe it can even be a
> staging ground for documentation that makes it into Twisted proper.
>   
Even if I re-suggested the wiki based documentation, I think it's 
important to be extra careful on how it's used. One thing I personally 
hate is projects whose documentation is basically wiki-based, and what 
you end having is a disconnected set of tips, many out of date, of how 
to do this and that. It could be OK it it's labeled 'Tipi-wiki' but not 
'Documentation' :).

As you say, I think that the wiki could be useful as a staging ground to 
build a formal documentation, but it shouldn't be even suggested for new 
users, since what they will probably find are many unfinished ideas.

Alternatively, a separate doc repo with sphinx based doc could be built 
so that it will allow for collaborative development making clear that is 
a work in progress and a product with 'releases'. I say a different repo 
to avoid having to give commit access to code for people who are working 
on doc,  maybe same repo with different permissions would be better. And 
I suggest sphinx to a) start from scratch and add existing doc as we see 
it's relevant, b) have a more flexible base than HTML docs, and for the 
reasons mentioned by Kevin (plus I want to learn it :P).

--
Santiago.