Documentation change collection methods (was Re: [mythtv] On Themes &
Jay R. Ashworth
jra at baylink.com
Thu Feb 3 21:21:39 UTC 2005
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
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
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.
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
More information about the mythtv-dev