Documentation change collection methods (was Re: [mythtv] On Themes & Theming)

[Jay R. Ashworth]

The quoting is mad in this, I don't know why I had so much trouble
following it.  I hope I've extracted it correctly.

On Thu, Feb 03, 2005 at 05:09:25AM -0500, J. Donavan Stanley wrote:
> Brad Templeton wrote:
> >On Wed, Feb 02, 2005 at 04:44:11PM -0500, Isaac Richards wrote:
> >>On Wednesday 02 February 2005 01:48 pm, Jason Gabriele wrote:
> >>>Use the wiki. The documentation is hard to update and no one ever feels
> >>>like writing stuff for it. That's why the wiki was created.

And Isaac replied:
> >>Thank you for reinforcing exactly why I don't like the wiki.

Which I don't quite follow, unless Isaac is conflating Jason's "hard to
update" comment with the wiki comments which surround it, which are
*supposed* (to my eyes) to be opposites:

"It's hard to distributively update cohesive flat file documentation.
So use the wiki instead, and when it stabilizes it can be merged back
in." 

That's what *I* thought Jason meant.

Then Brad noted:
> >Wikis have their plusses and minuses.  But for example, something a wiki
> >would be really good at would be the building of the release notes for
> >0.17, because you get a collaborative place where everybody can edit
> >in their own notes about changes they made or are documenting, and
> >then somebody can clean up and prioritize to produce something nice
> >for the docs.  A lot easier than having somebody have to hand coordinate
> >all that.   You can scan the cvs commit logs but they don't really have
> >good descriptions of the changes for users, nor are they sorted into
> >the categories users would like to see -- major new features, minor new
> >features, major fixes, minor fixes -- and such.

And then JDonavan followed up with:
> The release notes *are* on the wiki. Though I think only a couple people 
> have ever updated them aside from myself.  When I was indisposed for a 
> month or so nobody touched them.

And I'll observe that, while I've been pretty heavily wikipedia'd out
the last month, and didn't pay as much attention to *this* wiki as I'd
have liked, I wouldn't have done that particular job anyway, because,
IMO, it requires someone who understands at least the tactical
implications of each patch, to be able to expand them into civilian
language.

Non-civilians can just read the commit notices.  :-)

> The issue Isaac has, as well as myself to some extent, is that wiki 
> documentation is not being fed back to the core project documentation 
> thus creating two sources for docs instead of one.

And this is a valid point.  But the comparison issue here, so far as I
can see, is this: were people *submitting* any traditional patches to
the flat file doco, and if so, was Rich committing said patches.  In
short: was the *doco* sourced from CVS as well?

If that capability was there and no one was using it, but people *are*
contributing to the wiki, then I must assume that the wiki has a lower
imedance mismatch with non-developers, and that those who are cranky
are those whose responsibility the flat-doco is, who don't want to
extract the useful information from the wiki change stream and merge it
into their file.

It doesn't much matter *who* does that task, of course, and I don't
assert that it is *unimportant* to have some doco included with the
package as it ships.  But this is starting to sound a bit like a
territorial pissing match, to me: "why will those people update *that
guys* documentation, but not mine?"

I'm sure I didn't make any friends by this post, but really, pissing
people off is not my intent.  I just haven't seen any *cogent*
arguments about what, exactly, is so bad about capturing documentation
contributions via the wiki, as opposed to $OTHER_FASHION.

Cheers,
-- jra
-- 
Jay R. Ashworth                                                jra at baylink.com
Designer                          Baylink                             RFC 2100
Ashworth & Associates        The Things I Think                        '87 e24
St Petersburg FL USA      http://baylink.pitas.com             +1 727 647 1274

      If you can read this... thank a system adminstrator.  Or two.  --me