[Twisted-Python] Questions about adding documentation

[Kevin Horn]

On Fri, Jul 31, 2009 at 11:14 AM, Santiago Aguiar <santiago.aguiar at gmail.com
> wrote:

> 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' :).


In my experience, this what happens to every project that a) uses a wiki for
core documentation and b) has more than one person editing the wiki.

>
>
> 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.
>
>
I'd love to see a documentation "reboot" using Sphinx, but not if it's going
to be a half-baked, never-finished project.

Since Jessica started this thread, and is the only person (so far) who has
given any sort of commitment to actually working on new/revised docs, I'd
really like to hear her opinion.

Jessica?  You still out there?  Hope we haven't scared you off...

I'd also be interested in hearing the opinions of some of the core Twisted
guys on the various things we've been talking about here.  What do you guys
think about using a different docs system than what is being used now?  If
you guys are all dead set against it, there's not much point hashing out the
details...

Also, what do the Twisted core devs think about having a secondary
wiki/cookbook thingy outside of the core docs?

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090731/0f6218ba/attachment.htm