[Twisted-Python] Evangelism notes...

[Peter Saint-Andre]

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.

My $0.02.

Peter

-- 
Peter Saint-Andre
Jabber Software Foundation
http://www.jabber.org/people/stpeter.shtml