[Python-Dev] Moving the developer docs?

[Steven Elliott Jr]

Hello All,


I am new to this list, but I have been lurking around getting a feel for the
environment and processes. I had some discussion yesterday about the
developer documentation as well, since it’s what I do professionally. I am a
technical writer but also work in the web development arena (using Django).
In fact one of my projects now is to develop a comprehensive platform for
distributing online help, user documentation, etc. which I am just about to
put up on BitBucket (winter ’10). Anyway, that said, with regard to Wikis. I
have worked in several organizations where almost all of the development
documentation was maintained on a wiki. This can be great for getting up and
running with something quickly, but over time it becomes very unmanageable
and confusing.


What I have done in various organizations has been to create a system where
an official repository is kept with all of the *official* documentation and
a way for users (developers) to submit their proposals as to what they would
like to add and change. These proposals are kept in a tracker where they are
read and evaluated. Generally, some discussion ensues and the choices are
made as to what stays published or changed. This is what the system I am
writing is all about as well. It maintains the documentation, and allows for
users to comment on various parts of that documentation and submit requests
to change or add. The admins can then change or deny the documentation based
on community response. Anyway, I am not pitching my idea or trying to hump
my system but I will be releasing it before winter on BitBucket for anyone
to try and distribute freely.


I do however, discourage the use of wikis at all costs. It has been said
that they feel loose and unofficial, and although that my not be the intent,
over time this becomes reality.


Anyway, thank you for your time.


Warmest Regards,

Steve

On Thu, Sep 23, 2010 at 11:06 AM, Dirkjan Ochtman <dirkjan at ochtman.nl>wrote:

> On Thu, Sep 23, 2010 at 16:56, Guido van Rossum <guido at python.org> wrote:
> > I want to believe your theory (since I also have a feeling that some
> > wiki pages feel less trustworthy than others) but my own use of
> > Wikipedia makes me skeptical that this is all there is -- on many
> > pages on important topics you can clearly tell that a lot of effort
> > went into the article, and then I trust it more. On other places you
> > can tell that almost nobody cared. But I never look at the names of
> > the authors.
>
> Right -- I feel like wiki quality varies with the amount of attention
> spent on maintaining it. Wikis that get a lot of maintenance (or have
> someone devoted to "wiki gardening") will be good (consistent and up
> to date), while wikis that are only occasionally updated, or updated
> without much consistency or added to without editing get to feel bad.
> Seems like a variation of the broken window theory.
>
> So what we really need is a way to make editing the developer docs
> more rewarding (or less hard) for potential authors (i.e. python
> committers). If putting it in a proper VCS so they can use their
> editor of choice would help that, that seems like a good solution.
>
> Cheers,
>
> Dirkjan
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
> http://mail.python.org/mailman/options/python-dev/stevenrelliottjr1%40gmail.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100923/7ac6072b/attachment.html>