[Twisted-Python] Questions about adding documentation

[Jessica McKellar]

I am not scared off. In fact, I'm updating the
wiki/ContributingToTwistedLabs and related how-to-edit-documentation pages
right now.

I think adding content to and restructuring the howtos gives me a full plate
already, and to be honest I'm more interested in the content than the
presentation. People who have more experience with the successes and
failures of the various ways to organize project content online can make
that decision and I'd happily help move content over to another format
should that be necessary.

Thanks for all the help and feedback, everyone.

-Jessica

On Fri, Jul 31, 2009 at 12:55 PM, Kevin Horn <kevin.horn at gmail.com> wrote:

> 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
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090731/6b443815/attachment.html>