[Twisted-Python] Evangelism notes...

[Bob Ippolito]

On May 5, 2005, at 12:32 PM, Peter Saint-Andre wrote:

> On Thu, May 05, 2005 at 08:27:57AM +1000, Mary Gardiner wrote:
>
>> On Wed, May 04, 2005, Glyph Lefkowitz wrote:
>>
>>> Worse, this is a long-standing problem I don't see any effort  
>>> underway
>>> to rectify it.  Other open-source projects have gotten to this point
>>> and found huge, helpful teams of busy bees to fix the website, keep
>>> the documents up to date, wrangle the release notes and annotate the
>>> development process.
>>>
>>
>> What particular projects do you have in mind here? I ask because it
>> could well be useful to actually go to them and say "hey, where  
>> did you
>> find these people?" In particular, it would be useful to ask that
>> question of things that will be used by programmers: Python itself,
>> other languages developed/maintained by communities, the graphical
>> toolkits and other big libraries... (answers from, say, the GNOME  
>> user
>> documentation people might still be useful, but I think slightly less
>> so, because that documentation can be written by non-programmers).
>>
>> I can think of all kinds of answers ("they just appeared!", "we don't
>> merge features without review of their documentation," "we paid  
>> people,"
>> "we just love writing documentation," "there's these two crazy people
>> who just love writing documentation," "there's this one company who
>> employs our major developers and also employs some tech writers,")  
>> but I
>> don't know what the correct ones are.
>>
>
> In my experience (on Jabber and a few smaller projects), the hardest
> thing is finding people who want to write docs. Developers don't want
> to do it or don't have the time, and most folks who like to write are
> not especially technical. They might write a howto for end users, but
> documenting something like Twisted is beyond their ken. In the Jabber
> world I have been writing docs since mid-2000 but even so I mostly
> focus on protocol documentation because writing docs for various
> implementations (libraries, servers, clients) would be never-ending.

I think there's probably a lot of Twisted "end-user documentation"  
lying around in the form of presentations and tutorials given at  
various conferences.  If someone aggregates the links to all of that  
stuff, it would probably be a useful resource to new-ish users.

-bob