Re: [Twisted-Python] The End, also: documentation
Mary Gardiner wrote, utterly without influence from burning
This is my resignation as Twisted's lead documentation person.
Rest assured I'm not resigning due to any subset of: burning disillusionment, raging anger, or rampaging untreated mental illness. Rather, I have a bundle of other projects, and they're increasingly unrelated to Twisted, which means that I'm not using it for my own projects, and, sadly, I don't have the energy left over to task switch into an unrelated project enough to lead part of it.
I'm also, as it turns out, much more interested in reviewing and/or editing documentation than I am in writing it. The upside of this is that I'll continue to make myself available as a reviewer of documentation patches and/or an editor, if needed. Feel free to assign bugs on this basis. (I will probably not be reading the mailing list, but I don't make myself difficult to find on IRC.) I will unassign other bugs from myself soon.
This obviously leaves gaping holes in the greater Twisted universe for people anxious to advertise the glory of Twisted to the admiring masses. Do submit some documentation patches... It also leaves a vacancy for someone who is willing to be caretaker for the documentation as a whole, fixing minor bugs, farming out work and rearranging things according to their taste. Apply here, I suspect :)
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:
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 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).
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!"
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.
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...
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:
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?
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:
[...] 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.
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:
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?
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
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
Each of these sounds like a bug report, whether or not you attach a patch. -Mary
Mary Gardiner ha scritto:
On Thu, Apr 27, 2006, Manlio Perillo wrote:
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?
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
I have no problem with tickets, just I don't know to who assign them. Thanks and regards Manlio Perillo
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:
[...]
By the way, do you know anyone who might be similarly duped into becoming the website maintainer? (might you?)
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:
The site really need some works. Some links are still missing: http://twistedmatrix.com/projects/news/documentation/
and I really can't find manpages!
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.
...
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...
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