<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">Hello All,</span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px"><span style="letter-spacing: 0.0px"></span><br></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">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.</span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px"><span style="letter-spacing: 0.0px"></span><br></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">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.</span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px"><span style="letter-spacing: 0.0px"></span><br></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">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. </span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px"><span style="letter-spacing: 0.0px"></span><br></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">Anyway, thank you for your time.</span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px"><span style="letter-spacing: 0.0px"></span><br></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">Warmest Regards,</span></p>
<p style="margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica"><span style="letter-spacing: 0.0px">Steve</span></p><br><div class="gmail_quote">On Thu, Sep 23, 2010 at 11:06 AM, Dirkjan Ochtman <span dir="ltr"><<a href="mailto:dirkjan@ochtman.nl">dirkjan@ochtman.nl</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im">On Thu, Sep 23, 2010 at 16:56, Guido van Rossum <<a href="mailto:guido@python.org">guido@python.org</a>> wrote:<br>
> I want to believe your theory (since I also have a feeling that some<br>
> wiki pages feel less trustworthy than others) but my own use of<br>
> Wikipedia makes me skeptical that this is all there is -- on many<br>
> pages on important topics you can clearly tell that a lot of effort<br>
> went into the article, and then I trust it more. On other places you<br>
> can tell that almost nobody cared. But I never look at the names of<br>
> the authors.<br>
<br>
</div>Right -- I feel like wiki quality varies with the amount of attention<br>
spent on maintaining it. Wikis that get a lot of maintenance (or have<br>
someone devoted to "wiki gardening") will be good (consistent and up<br>
to date), while wikis that are only occasionally updated, or updated<br>
without much consistency or added to without editing get to feel bad.<br>
Seems like a variation of the broken window theory.<br>
<br>
So what we really need is a way to make editing the developer docs<br>
more rewarding (or less hard) for potential authors (i.e. python<br>
committers). If putting it in a proper VCS so they can use their<br>
editor of choice would help that, that seems like a good solution.<br>
<br>
Cheers,<br>
<font color="#888888"><br>
Dirkjan<br>
</font><div><div></div><div class="h5">_______________________________________________<br>
Python-Dev mailing list<br>
<a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
<a href="http://mail.python.org/mailman/listinfo/python-dev" target="_blank">http://mail.python.org/mailman/listinfo/python-dev</a><br>
Unsubscribe: <a href="http://mail.python.org/mailman/options/python-dev/stevenrelliottjr1%40gmail.com" target="_blank">http://mail.python.org/mailman/options/python-dev/stevenrelliottjr1%40gmail.com</a><br>
</div></div></blockquote></div><br>