overheard on IRC:

> We also need to add a note on Plugins.TWiki regarding installing all plugins - saying that after plugin is installed, you have to go back to configure to enable it. Hmmm... Plugins.TWiki has one of those "Do not edit" comments at the end. Guess I can't add a comment about installing the plugins.
> Lynnwood wonders at what point in all this programmers automated efficiency we loose most of the collaborative benefit of a wiki?

A concrete example: JoeUser sees that DakarReleaseNotes does not have a link to TWikiUpgradeGuide. In order to do something about it s/he needs to a) file a bug report Item597, b) someone with svn write access needs to edit the .txt file in an svn working copy, c) developer needs to checkin the changes (SVN 6786) (after making sure that r.1.12 is changed to $Rev and JoeDev to TWikiContributor Item613), d) wait for automated cron job which runs every X minutes (15?) to update the website

This process is quite a distance from wikidom. "A defining characteristic of wiki technology is the ease with which pages can be created and updated."*

There is a need to keep a formal procedure for svn checkins. It ensures every checkin is documented and increases the quality of code by virture of a few extra moments of reflection. When it comes to documentation though, this procedure sucks rocks. Gone is drive-by fixing of typos, leaving only the determined and committed to keep things up to date while adding more to the inbox of those who would otherwise be spending their time fixing and writing code.

How to fix this?

One possibility:

• add a mandatory "summary of changes" input to the edit screen of topics in the TWiki web (this is an enhancement request anyway)
• on save the .txt file is checked into svn using the summary field as the checkin log message (perhaps with a prefix like Doc123: or WikiEdit123: ?)

Other solutions?

---

I set the priority for this item as normal even though that makes the issue sound not very significant rather than the broad and far reaching force it really is. None of the other categories really fit any better though. --MW

---

Yes, I totally agree. This is something we need to figure out - the current process is only an artefact of needing to be able to manage and track the released topics to be able to produce a repeatable release build. We were always intending to write an SVN store, and Crawford has gone part of the way -- SD

---

See follow-up in TWiki:Codev.DakarDocumentationModelIsBroken and Item628.

PTh

---

deferred to TWiki:Codev.EdinburghRelease as one of the first things to do in each release is to review previous development practices. -- WN

Undeferred, post Dakar CC

---

Irritated by the lack of progress on this issue, I just wrote a script that synchs the content of the 'TWiki' web on this site - it handles the %SECTION tags to update just the document body and not the discussion. The script is written to update a local checkout (it does not check in) but it could easily be extended to check in changes synched from t.o. This could then be run as a cron job.

However it emerges from running the script that the TWiki web on t.o is a long way out of synch with the doc in Subversion. A quick look through shows that the doc in Subversion is more recent and accurate. Before my script can be installed as a cron, the TWiki web on t.o therefore needs to be synched with the latest doc in subversion. I did not make the script change the doc on t.o, as my understanding is that that is the preferred master. So here's what needs doing:

1. Synch the topic content on t.o with SVN (the bit in the %STARTSECTION{"distributiondoc"}%)
2. Ensure that the %STARTSECTION{"distributiondoc"}% exists in all t.o versions of distributed docs
3. Ensure that t.o. versions of all docs in SVN actually exist

CC

Modified the script to support synch both ways. Flipped back to confirmed because I'm not doing any more on this.

CC