Re: [Twisted-Python] The End, also: documentation
Mary Gardiner wrote, utterly without influence from burning
Mary, this Twisted user for one really appreciates the efforts you've put forth. Indeed, as one of the biggest complainers about Twisted's docs, I probably appreciate those efforts more than many users. (That sounds backwards until you think about it for a while, like a lot of legal language.) I'm thinking about suggesting (gasp!) myself as your replacement. The logical, responsible part of my brain is telling me that I'm insane for doing this. But there's another part of my brain that has an illogical, probably unhealthy fascination with Twisted and is raising its hand and squirming on the uncomfortable wooden schooldesk chair with those huge uncomfortable screw heads sticking out, yelling "Call on me! Call on me!" As a registered patent agent (http://eepatents.com), I do a lot of writing as part of my work and bill quite a bit per hour for doing so. (Here that logical, responsible part is screaming, "So WHY do you want to do more writing for FREE?") I have complained and whined about the, shall we say "mixed," state of Twisted's docs for years now on #twisted and am intrigued by the idea of putting my mouth (dictation) where my mouth (complaints) is. Plus, (branch) commit access would be kind of cool for writing those docstrings where I just can't stand seeing those glaring holes right below "def" or "class"... It goes without saying (but I'll say it anyway) that there is and would be absolutely no professional relationship between me and the Twisted project. (Most free software types aren't all that enamored with patents, anyhow...) I have kind of enjoyed the decidedly unprofessional relationship that has developed on #twisted, though. Comments welcome. Any positive ones will likely be viewed with suspicion and will raise pangs of regret at my making this rash posting. The negative ones will likely be viewed with relief, at least by the aforementioned logical, responsible part... Best regards, Ed Suominen Logical, responsible patent agent Inexplicably passionate Twisted dabbler
On Wed, 26 Apr 2006 09:40:45 -0700, Ed Suominen <general@eepatents.com> wrote:
I think that, oddly enough, Mary's resignation comes because she was the most dilligent member of the team, taking her documentation-maintenance responsibilities more seriously than almost anyone else over the packages they maintain (myself included).
No need to insist - with the level of competition we usually have, you're in! The position of "documentation maintainer" is a bit unusual since it was actually taken consciously and willingly. Usually the protocol is this: I appoint someone for a task, which they are not qualified to do. Then, they have to fight a bear if they don't want to do it. Now that you've volunteered, there's no getting out of it. I mean, do you want to fight a bear? I wouldn't. Bears are *scary* - just ask Stephen Colbert.
Well, I guess you could consider my comment positive. I think you'll do a great job, since few people seem to care so much about documentation. By the way, do you know anyone who might be similarly duped into becoming the website maintainer? (might you?)
By the way, do you know anyone who might be similarly duped into becoming the website maintainer? (might you?)
Duped, indeed. OK, I'll bite. Where do I sign? -- Nicola Larosa - http://www.tekNico.net/ Our society definitely needs a serious conversation about the fundamental freedoms we are sacrificing in a misguided attempt to keep us safe from terrorism. It feels both surreal and sickening to have to defend our fundamental freedoms against those who want to stop people from sharing music. How is it possible that we can contemplate so much damage to our society simply to protect the business model of a handful of companies? -- Bruce Schneier, December 2005
On Thu, 27 Apr 2006 10:41:31 +0200, Nicola Larosa <nico@teknico.net> wrote:
OK, I'll bite. Where do I sign?
Work already cut out and waiting, great. Taking a hint from #1517, I checked out WebSite, and will go over it soon. If anybody has any hint, don't be shy. :-) -- Nicola Larosa - http://www.tekNico.net/ The police and the military have fundamentally different missions. The police protect citizens. The military attacks the enemy. When you start giving police powers to the military, citizens start looking like the enemy. -- Bruce Schneier, December 2005
glyph@divmod.com ha scritto:
Just to known. Suppose I found some time to document some parts of Twisted. Many things in twisted.python are undocumented, log is rougly documented and usage docs are not really complete. I have to submit a ticket/patch? By the way: here are some parts for witch I would like to see documentation: 1) twisted.python 2) description of design patterns used in twisted 3) all(?) interfaces, like IConsumer 4) parts of twisted deprecated/unmaintained/abandoned/not to be used 5) parts of twisted that need recoding (twisted.news?) 6) servers used in production enviroment with use cases Thanks and regards Manlio Perillo
On Thu, Apr 27, 2006, Manlio Perillo wrote:
This would be the usual way to do it. I used to accept some through email to, but that just adds another step for the person you mail them to: they file a bug based on your mail. I had a post about what made a good docs bug here: http://twistedmatrix.com/pipermail/twisted-python/2004-June/008071.html
Each of these sounds like a bug report, whether or not you attach a patch. -Mary
On Fri, Apr 28, 2006, Manlio Perillo wrote:
I have no problem with tickets, just I don't know to who assign them.
It seems the appropriate rituals have performed and Ed is now the lead documentation maintainer for Twisted. So they should be assigned to him, but I don't know what his bugtracker login is. I think it's possible not to assign tickets to anyone (I don't know trac very well), so that's the backup plan. -Mary
glyph@divmod.com ha scritto:
The site really need some works. Some links are still missing: http://twistedmatrix.com/projects/news/documentation/ and I really can't find manpages! Regards Manlio Perillo
On Thu, Apr 27, 2006, Manlio Perillo wrote:
This kind of information should be submitted as a bug at http://twistedmatrix.com/trac/newticket and marked as belonging to the 'website' component. (I tended to prefer each individual problem be filed as a separate bug, this mail sounds like two bugs.) -Mary
On Wed, Apr 26, 2006, Ed Suominen wrote:
I'm thinking about suggesting (gasp!) myself as your replacement.
...
You'll notice I've reassigned some tickets to you and will continue to do so over the next few days. I'm not sure how your logical and responsible part will feel about this... you can grab me on IRC as hypatia for clarification of anything I filed... -Mary
On Wed, 26 Apr 2006 09:40:45 -0700, Ed Suominen <general@eepatents.com> wrote:
I think that, oddly enough, Mary's resignation comes because she was the most dilligent member of the team, taking her documentation-maintenance responsibilities more seriously than almost anyone else over the packages they maintain (myself included).
No need to insist - with the level of competition we usually have, you're in! The position of "documentation maintainer" is a bit unusual since it was actually taken consciously and willingly. Usually the protocol is this: I appoint someone for a task, which they are not qualified to do. Then, they have to fight a bear if they don't want to do it. Now that you've volunteered, there's no getting out of it. I mean, do you want to fight a bear? I wouldn't. Bears are *scary* - just ask Stephen Colbert.
Well, I guess you could consider my comment positive. I think you'll do a great job, since few people seem to care so much about documentation. By the way, do you know anyone who might be similarly duped into becoming the website maintainer? (might you?)
By the way, do you know anyone who might be similarly duped into becoming the website maintainer? (might you?)
Duped, indeed. OK, I'll bite. Where do I sign? -- Nicola Larosa - http://www.tekNico.net/ Our society definitely needs a serious conversation about the fundamental freedoms we are sacrificing in a misguided attempt to keep us safe from terrorism. It feels both surreal and sickening to have to defend our fundamental freedoms against those who want to stop people from sharing music. How is it possible that we can contemplate so much damage to our society simply to protect the business model of a handful of companies? -- Bruce Schneier, December 2005
On Thu, 27 Apr 2006 10:41:31 +0200, Nicola Larosa <nico@teknico.net> wrote:
OK, I'll bite. Where do I sign?
Work already cut out and waiting, great. Taking a hint from #1517, I checked out WebSite, and will go over it soon. If anybody has any hint, don't be shy. :-) -- Nicola Larosa - http://www.tekNico.net/ The police and the military have fundamentally different missions. The police protect citizens. The military attacks the enemy. When you start giving police powers to the military, citizens start looking like the enemy. -- Bruce Schneier, December 2005
glyph@divmod.com ha scritto:
Just to known. Suppose I found some time to document some parts of Twisted. Many things in twisted.python are undocumented, log is rougly documented and usage docs are not really complete. I have to submit a ticket/patch? By the way: here are some parts for witch I would like to see documentation: 1) twisted.python 2) description of design patterns used in twisted 3) all(?) interfaces, like IConsumer 4) parts of twisted deprecated/unmaintained/abandoned/not to be used 5) parts of twisted that need recoding (twisted.news?) 6) servers used in production enviroment with use cases Thanks and regards Manlio Perillo
On Thu, Apr 27, 2006, Manlio Perillo wrote:
This would be the usual way to do it. I used to accept some through email to, but that just adds another step for the person you mail them to: they file a bug based on your mail. I had a post about what made a good docs bug here: http://twistedmatrix.com/pipermail/twisted-python/2004-June/008071.html
Each of these sounds like a bug report, whether or not you attach a patch. -Mary
On Fri, Apr 28, 2006, Manlio Perillo wrote:
I have no problem with tickets, just I don't know to who assign them.
It seems the appropriate rituals have performed and Ed is now the lead documentation maintainer for Twisted. So they should be assigned to him, but I don't know what his bugtracker login is. I think it's possible not to assign tickets to anyone (I don't know trac very well), so that's the backup plan. -Mary
glyph@divmod.com ha scritto:
The site really need some works. Some links are still missing: http://twistedmatrix.com/projects/news/documentation/ and I really can't find manpages! Regards Manlio Perillo
On Thu, Apr 27, 2006, Manlio Perillo wrote:
This kind of information should be submitted as a bug at http://twistedmatrix.com/trac/newticket and marked as belonging to the 'website' component. (I tended to prefer each individual problem be filed as a separate bug, this mail sounds like two bugs.) -Mary
On Wed, Apr 26, 2006, Ed Suominen wrote:
I'm thinking about suggesting (gasp!) myself as your replacement.
...
You'll notice I've reassigned some tickets to you and will continue to do so over the next few days. I'm not sure how your logical and responsible part will feel about this... you can grab me on IRC as hypatia for clarification of anything I filed... -Mary
participants (6)
-
Ed Suominen -
glyph＠divmod.com -
Jean-Paul Calderone -
Manlio Perillo -
Mary Gardiner -
Nicola Larosa