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

[Jay R. Ashworth]

On Thu, Feb 03, 2005 at 08:59:31PM -0500, Jason Gabriele wrote:
> > 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.
> 
> I never meant that anyone should stop working on the official documentation.

I didn't think you had.

I can see that it might have been unclear, even in my restatement.

"It's hard to distributively update..." is merely an observation of
fact; as I point out later, clearly, I don't mean that no one should
ever update the flat doco again.

> What I meant is it would be easier to add things to the wiki. Sure
> they could be merged into the official documentation afterwards. I
> would be much more likely to add something if I could just hit "edit
> page" and add an extra line then hit submit. The original poster
> wanted a "communal" place to put information on theming so I suggested
> the wiki.

And that's precisely why I started the User Manual project at mythtv.info.
So there would be a place for contributions like that.  Cause, and
frankly, coders don't always get this, it really *is not* easy to
submit updates to doco.  I *am* a coder, though I'm not Isaac, and *I*
don't really understand diff and patch.

In my view, what it comes down to is: if you want to capture the
knowledge in the minds of the users, you have to make the capture
mechanism easy enough to use that they'll actually use it.  If you want
to limit that solely to the flat-file documentation, then *one person*
is going to have to be committing the changes, and either he'll have to
do a bunch of massaging, or people will have to submit nice pretty
source diffs.

Me, I'd say that having users submit to the Wiki and having RichK steal
the things he finds a) useful and b) accurate into the flat file is the
bext of both worlds.

Clearly, some people don't agree with me.  Perhaps if I go hunt up the
last "wiki's are bad" thread (:-) I'll find out why.

Perhaps not.

Where is that again?

Cheers,
-- jar
-- 
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