[Twisted-Python] Questions about adding documentation
tarjei at nu.no
Mon Aug 3 03:35:25 EDT 2009
A lot has been said in this discussion but I'll add one thing.
On 07/31/2009 06:32 PM, Reza Lotun wrote:
>> 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:
What I miss is a comment system related to the API docs so that it is
possible for beginners and others to add small notes there without
having to make a ticket, wait for it to be assigned etc.
Apart from that I will just welcome anyone who writes documentation.
>> 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?
Mobil: 920 63 413
More information about the Twisted-Python