|
Steve Holden
steve at holdenweb.com
Tue Nov 28 20:18:10 EST 2006
Martin Stoufer wrote: [top-posting rectified: please don't do that ;-)] >>> Sections 4, 5 and 6 (API, Apache Configuration Directives and Standard >>> Handlers) of the current docs stay with in the source distribution. >>> Everything else would be a candidate for the wiki. (We should likely >>> decide which should go in the wiki vs the modpython.org website vs the >>> httpd.apache.org/modules/mod_python website). >> >> Yes, chapters 4-6 seem to be the core "official" documentation >> and make sense to lock down similar to the source code. >> If other chapters like the tutorials are separated at all, putting them >> in a wiki seems to make the most sense to me. >> >> Things like the release change notes should probably either be >> read-only static web pages, or perhaps moved to a protected wiki >> area. Perhaps it would be sufficient to use MoinMoin ACLs for >> this. That way the content is fixed, but still easily linked to, etc. >> >> Is this wiki effort a good time to finally separate somewhat the >> core mod_python from PSP in how the documentation is >> organized? >> > My last collaboration project had to learn this the hard way. All our > software design/usage documentation was put up on a WiKi and slowly > dissolved into a morass of incorrect and incomplete entries. Those not > fully versed in the inner workings of the software would post changes > and suggestions (hacks in my book!) not knowing how it would effect > other components. Not because they were stupid, they just didn't fully > understand. > > I have been an ardent supporter that real documentation should flow from > those who know to those who don't. This doesn't mean that this info is > static forever. There just has to be an absolute stop-gate in the > feedback loop that can analyze and determine what should be changed. I > would look to maintain both a read-only section and slowly incorporate > only the very sound ideas from the world-writable area. > > Such a "change control" mechanism would work best if it is started > early. I would like to volunteer to review and help approve content in > the 'OS install' area. > Look at what Fredrik Lundh is doing with the "(Semi-Official) Python FAQ" at http://effbot.org/pyfaq/ - it allows comments, but the comments are folded in by someone "in charge". The developers could get to say who was "in charge" at any time. While this approach does have merits, if the comments aren't sensibly processed then the text can biodegrade in the same way as a wiki. But I can testify that it does encourage people to contribute: while writing this mail I clicked the "random page" button a few times until I found and article I could usefully add comments for, and did so. regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden
|