Re: [Twisted-Python] Questions about adding documentation

On Aug 2, 2009, at 12:41 AM, Glyph Lefkowitz wrote: On Sat, Aug 1, 2009 at 11:30 PM, Steve Steiner (listsin) > wrote: Where would we put an "inventory" project for it to be most useful? As JP mentioned earlier in this thread, some work has already taken place here:

Re: [Twisted-Python] Questions about adding documentation

2009/8/3 tarjei : > 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

Re: [Twisted-Python] Questions about adding documentation

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 basicall

Re: [Twisted-Python] Questions about adding documentation

On Sat, Aug 1, 2009 at 11:30 PM, Steve Steiner (listsin) < list...@integrateddevcorp.com> wrote: > Where would we put an "inventory" project for it to be most useful? >> > > As JP mentioned earlier in this thread, some work has already taken place > here:

Re: [Twisted-Python] Questions about adding documentation

I get it, really. I do tend to use a lot of words to get things across. Sorry ;-). Duly noted ;-). Where would we put an "inventory" project for it to be most useful? As JP mentioned earlier in this thread, some work has already taken place here:

Re: [Twisted-Python] Questions about adding documentation

On Sat, Aug 1, 2009 at 12:11 AM, Steve Steiner < list...@integrateddevcorp.com> wrote: > > I hope you can see why I want to hold on to our current toolchain > > until we have someone around who has demonstrated a much deeper > > commitment to documentation than anyone yet has. For example, > > St

Re: [Twisted-Python] Questions about adding documentation

> I hope you can see why I want to hold on to our current toolchain > until we have someone around who has demonstrated a much deeper > commitment to documentation than anyone yet has. For example, > Steve, if you close 100 existing documentation tickets in the next > week, then make the e

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 11:10 PM, Steve Steiner (listsin) < list...@integrateddevcorp.com> wrote: > Since "everything" is not in the build system anyway, perhaps starting > a branch, in a new build system (Sphinx), where we pull things in, one > chunk at a time, will not be a hit and run approach,

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 10:25 PM, Itamar Shtull-Trauring wrote: > Could you file some bugs to that effect, so we don't forget these > suggestions? Thanks! Done: http://twistedmatrix.com/trac/ticket/3945 The formatting on the description is off though (I tried to make bullet points and failed),

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 4:23 PM, Glyph Lefkowitz wrote: ... > I certainly wouldn't mind switching to a tool that has lots of fancy > features that lore lacks, but a hit-and-run approach where we just > switch tools in the hopes that it will make something better may > leave us in a worse situati

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 10:25 PM, Itamar Shtull-Trauring wrote: > On Fri, 2009-07-31 at 15:37 -0400, Ying Li wrote: > >> version (currently 8.2.0) but this is meaningless to me. I think a >> big improvement would be putting in a small bit of context around the >> documentation , such as: >> >> * whe

Re: [Twisted-Python] Questions about adding documentation

On Fri, 2009-07-31 at 15:37 -0400, Ying Li wrote: > version (currently 8.2.0) but this is meaningless to me. I think a > big improvement would be putting in a small bit of context around the > documentation , such as: > > * when the howto/tutorial was last updated > * what version (of deferreds/

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 1:16 PM, Jessica McKellar < jessica.mckel...@gmail.com> wrote: > I am not scared off. In fact, I'm updating the > wiki/ContributingToTwistedLabs and related how-to-edit-documentation pages > right now. > I see the edits in the timeline. They look great! Thanks! :-D Do y

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 3:37 PM, Ying Li wrote: > On Fri, Jul 31, 2009 at 10:19 AM, Santiago > Aguiar wrote: >> My suggestion would be that more than *adding* documentation, I would >> suggest to first search-and-destroy deprecated documentation. For me, >> one of the most frustrating parts of using

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 2:15 PM, Kevin Horn wrote: > Well, pragmatism is my basic reason for not liking wikis for docs. :) > > For me, it boils down to every time I've worked on or with a project > that used wikis for docs (assuming that the project is of at least > moderate size and has more than

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 10:19 AM, Santiago Aguiar wrote: > My suggestion would be that more than *adding* documentation, I would > suggest to first search-and-destroy deprecated documentation. For me, > one of the most frustrating parts of using twisted was reading through > the twisted core doc, t

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 12:57 PM, Phil Christensen wrote: > > On Jul 31, 2009, at 1:34 PM, Kevin Horn wrote: > > >Also, what do the Twisted core devs think about having a secondary > > >wiki/cookbook thingy outside of the core docs? > > > > As a staging area for development of future core docs, I

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 12:16 PM, Jessica McKellar < jessica.mckel...@gmail.com> wrote: > I am not scared off. In fact, I'm updating the > wiki/ContributingToTwistedLabs and related how-to-edit-documentation pages > right now. > Great! I think that this is a critical first step. > I think addi

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 1:34 PM, Kevin Horn wrote: > >Also, what do the Twisted core devs think about having a secondary > >wiki/cookbook thingy outside of the core docs? > > As a staging area for development of future core docs, I think I would > recommend using a version control system (perhaps a di

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 12:11 PM, Kevin Horn wrote: > On Fri, Jul 31, 2009 at 11:52 AM, Phil Christensen > wrote: > >> >> My only question about Sphinx, isn't it just for API docs? Also, can >> it interpret Zope interfaces like pydoctor can? >> > > AFAIK Sphinx does not have support for Zope int

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 12:11 PM, Jean-Paul Calderone wrote: > On Fri, 31 Jul 2009 11:55:08 -0500, Kevin Horn > wrote: > > [snip] > > > >I'd love to see a documentation "reboot" using Sphinx, but not if it's > going > >to be a half-baked, never-finished project. > > > > [snip] > > > >I'd also be

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 1:11 PM, Jean-Paul Calderone wrote: > As a staging area for development of future core docs, I think I would > recommend using a version control system (perhaps a distributed one), > not a wiki. What I was suggesting originally was that a wiki would be a staging ground for th

Re: [Twisted-Python] Questions about adding documentation

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

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 11:52 AM, Phil Christensen wrote: > > My only question about Sphinx, isn't it just for API docs? Also, can > it interpret Zope interfaces like pydoctor can? > Sphinx is great for writing all sorts of docs. At its core, it's basically a system for gluing together a bunch o

Re: [Twisted-Python] Questions about adding documentation

On Fri, 31 Jul 2009 11:55:08 -0500, Kevin Horn wrote: > [snip] > >I'd love to see a documentation "reboot" using Sphinx, but not if it's going >to be a half-baked, never-finished project. > > [snip] > >I'd also be interested in hearing the opinions of some of the core Twisted >guys on the various

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 11:14 AM, Santiago Aguiar 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

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 12: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 d

Re: [Twisted-Python] Questions about adding documentation

> 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

Re: [Twisted-Python] Questions about adding documentation

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 > stagi

Re: [Twisted-Python] Questions about adding documentation

Hi All, > Well, if there *were* to be a change in the documentation system used, I > would push for moving to Sphinx, rather than a wiki. > > * it's rapidly becoming a "standard" for docs in the Python world > * it has lots of neat  features > * it can be version controlled > * multiple output for

Re: [Twisted-Python] Questions about adding documentation

- Original Message - From: Kevin Horn "Sometimes I think what is needed is someone who knows basically nothing about Twisted to go about learning it...and then writing down how they did it." I'm trying to do this, by keeping notes as I learn twisted to build a custom email system. It's ha

Re: [Twisted-Python] Questions about adding documentation

On Fri, Jul 31, 2009 at 9:34 AM, Phil Christensen wrote: > On Jul 31, 2009, at 10:19 AM, Santiago Aguiar wrote: > > It could also be a good idea to try to make it more wiki-like at the > > beginning; I think there's quite a lot of people that would like to > > contribute with this, but having diff

Re: [Twisted-Python] Questions about adding documentation

On Jul 31, 2009, at 10:19 AM, Santiago Aguiar wrote: > It could also be a good idea to try to make it more wiki-like at the > beginning; I think there's quite a lot of people that would like to > contribute with this, but having different documents/styles for > different areas of the doc is not goo

Re: [Twisted-Python] Questions about adding documentation

Hi Jessica! I'm quite a newbie at twisted yet, and a newcomer to the project, so I do think that twisted documentation is one of it's more problematic areas!. My suggestion would be that more than *adding* documentation, I would suggest to first search-and-destroy deprecated documentation. For

Re: [Twisted-Python] Questions about adding documentation

On Thu, Jul 30, 2009 at 10:35 PM, Jean-Paul Calderone wrote: > On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar < > jessica.mckel...@gmail.com> wrote: > >Hi everyone, > > > >I would like to help Twisted by adding documentation or reviewing existing > >documentation. However, I don't see many (

Re: [Twisted-Python] Questions about adding documentation

On Thu, Jul 30, 2009 at 11:58 PM, Steve Steiner (listsin) wrote: > > On Jul 30, 2009, at 11:51 PM, Kevin Horn wrote: > >> Steve. >> >> Same thing happened to me.  In my case it was corrected by a page >> refresh. > > Yah, it's just a little scary when Twisted's own site does things like > this. >

Re: [Twisted-Python] Questions about adding documentation

On Jul 30, 2009, at 11:51 PM, Kevin Horn wrote: > Steve. > > Same thing happened to me. In my case it was corrected by a page > refresh. Yah, it's just a little scary when Twisted's own site does things like this. S ___ Twisted-Python mailing l

Re: [Twisted-Python] Questions about adding documentation

Steve. Same thing happened to me. In my case it was corrected by a page refresh. Kevin Horn On Thu, Jul 30, 2009 at 10:45 PM, Steve Steiner (listsin) < list...@integrateddevcorp.com> wrote: > > On Jul 30, 2009, at 11:35 PM, Jean-Paul Calderone wrote: > > Here are a few tickets in particular wh

Re: [Twisted-Python] Questions about adding documentation

On Jul 30, 2009, at 11:35 PM, Jean-Paul Calderone wrote: > Here are a few tickets in particular which I think it would be > worthwhile to > resolve: > >http://twistedmatrix.com/trac/ticket/1136 >http://twistedmatrix.com/trac/ticket/1627 >http://twistedmatrix.com/trac/ticket/3784 >

Re: [Twisted-Python] Questions about adding documentation

On Thu, 30 Jul 2009 20:49:54 -0400, Jessica McKellar wrote: >Hi everyone, > >I would like to help Twisted by adding documentation or reviewing existing >documentation. However, I don't see many (any?) unassigned tickets regarding >documentation of specific items, and because I am quite new to Twi

[Twisted-Python] Questions about adding documentation

Hi everyone, I would like to help Twisted by adding documentation or reviewing existing documentation. However, I don't see many (any?) unassigned tickets regarding documentation of specific items, and because I am quite new to Twisted this makes it hard for me to determine where you wish I would