[Twisted-Python] Questions about adding documentation

[Reza Lotun]

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

I agree - the wiki shouldn't *replace* the documentation, but the
reality is I have loads of bookmarks of blog posts and discussions on
the mailing list, and it'd be nice if I could to go one place to find
all that type of info. A "recipe" or "cookbook" wiki might be all we
need, with the ability to comment on each. The Activestate Python
Cookbook is kinda what I'm thinking about:
http://code.activestate.com/recipes/langs/python/

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

I haven't yet looked at lore or sphinx, but is there a way to support
sphinx via lore?

Reza

-- 
Reza Lotun
+44 (0)7521 310 763
rlotun at gmail.com