|
Martin Stoufer
MCStoufer at lbl.gov
Tue Nov 28 19:05:58 EST 2006
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. >> 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? > -- * Martin C. Stoufer * * DST/DIDC/ITG * * Lawrence Berkeley National Lab * * MS 50B-2239 510-486-8662 * -------------- next part -------------- A non-text attachment was scrubbed... Name: smime.p7s Type: application/x-pkcs7-signature Size: 3423 bytes Desc: S/MIME Cryptographic Signature Url : http://mm_cfg_has_not_been_edited_to_set_host_domains/pipermail/mod_python/attachments/20061128/6bbfbead/smime-0001.bin
|