[mythtv-users] Myth Documentation, was: Please shut up!

Rod Smith mythtv at rodsbooks.com
Mon Jan 29 16:54:16 UTC 2007


On Monday 29 January 2007 11:22, Steven Adeff wrote:
> On 1/29/07, Rod Smith <mythtv at rodsbooks.com> wrote:
> > On Monday 29 January 2007 09:34, Steven Adeff wrote:
> > > As for version'ing the wiki, and a note about this *should* exist on
> > > the home page, it is assumed on the wiki that unless the text says
> > > otherwise the information pertains to the currently released version.
> > > If upon the release of a new version the information becomes outdated
> > > it should be changed as soon as it is noticed, with the old
> > > information being dated to the previous release (so when 0.21 comes
> > > out, the information would say it pertains to 0.20).
> >
> > That's a very labor-intensive proposition. Do YOU want to go through a
> > flag EVERY wiki entry the day a new version of MythTV is released?
> > (Remember you'll have to check edit dates, too, just in case somebody's
> > rushed in with some brand-new information before you get around to
> > checking an entry.) Short of a coordinated effort to do this immediately,
> > it won't get done. IMHO, the idea of version-flagging every wiki entry as
> > its made makes far more sense. Ideally this would be part of the
> > submission process, but I have no idea if the wiki software supports such
> > a thing.
>
> I believe you did not quote the text you believe or wanted to quote.

No, I quoted precisely what I wanted to quote.

> I'm not saying we should flag every wiki page. Just place a note on
> the wiki home page. Add notes to pages for information pertaining to
> older versions of Myth and let the information not noted be assumed
> current, or un-updated. Flagging pages for current methodologies does
> nothing to help maintenance.

Under your scenario, one of two things happens:

1) *EVERY* page will *HAVE* to be updated with version information as
   soon as possible after a new MythTV release. (Or possibly after
   other software release, such as updated kernel drivers for pages
   that document kernel features.) If this isn't done....

2) Readers will not know whether the information is current or not.
   Your "assumed current, or un-updated" state is completely useless
   to readers. It's like putting bread in black bags every day for
   two weeks, putting the whole lot on a store shelf, and selling it
   as "maybe good, maybe moldy." Of course, this is basically what
   we've got now, just without the "maybe good, maybe moldy"
   disclaimer.

As the point of a wiki is to provide useful information to readers, I 
personally consider option #2 undesirable verging on unacceptable. That 
leaves #1 -- individual entries *MUST* be updated *IMMEDIATELY* upon release 
of a new version, at least to flag their newly-uncurrent status, to prevent 
reader confusion. Of course, they should eventually be updated to reflect any 
changes to the software, too, but that's true whether or not the entries were 
version-flagged to begin with.

It's much simpler and clearer to include version information with each wiki 
entry when its made. That should minimize confusion or uncertainty about the 
relevance of the information to any given version of the software, or at 
least alert readers to the fact that the wiki doesn't cover a given topic 
with respect to whatever software they're running, if that's the case.

Added screen clutter is a minor issue in comparison, IMHO.

-- 
Rod Smith
http://www.rodsbooks.com


More information about the mythtv-users mailing list