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

Steven Adeff adeffs.mythtv at gmail.com
Mon Jan 29 19:07:42 UTC 2007


On 1/29/07, Rod Smith <mythtv at rodsbooks.com> wrote:
> 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.


Well, we can make versioning a policy of adding to the wiki. We can
also ask that any pages being edited without version information to
add versioning information. Eventually everything will include the
version it applies to.  Perhaps we can even figure out a way to create
a template such that {{{0.19}}} will format the page nicely.

As for immediate updating. hahaha. Don't count on it. Not that it
doesn't get updated fairly well, but until you pay someone to do the
work expect it to be done by the first person that notices the change
and knows what to change.

-- 
Steve
Before you ask, read the FAQ!
http://www.mythtv.org/wiki/index.php/Frequently_Asked_Questions
then search the Wiki, and this list,
http://www.gossamer-threads.com/lists/mythtv/
Mailinglist etiquette -
http://www.mythtv.org/wiki/index.php/Mailing_List_etiquette


More information about the mythtv-users mailing list