[mythtv-users] Wiki Week - an appeal

[f-myth-users at media.mit.edu]

    > Date: Thu, 3 Aug 2006 16:19:56 +0100
    > From: "Justin Hornsby" <justin.hornsby at gmail.com>

I think you've got it backwards on how this should probably work.
See below.

    > In all fairness, I think the assumption should always be (and is now)
    > that users are running the latest stable version.

There are three problems here:
(a) Many users run old versions.  Several people here are talking
    about running 0.18.x, and about perhaps skipping directly to 0.20
    at some point.  (That's my plan as well.)  In fact, I'm willing to
    assert, completely without proof, that users running old versions
    are -underrepresented- on these lists, because they have set them
    up, they work, and they don't bother to read or (especially) post
    here because if it works, there's no point in reading hundreds of
    messages a day for what they view as an appliance.
(b) Much bigger problem---when people typically edit a wiki (any wiki),
    they often don't bother to specify what version they're talking about,
    or they say "latest version" without realizing that this term is
    instantly ambiguous.  (And no, you can't go by an edit date on the
    page, because one -part- of the page might have been updated; in
    the limit you'd have to look at the edit history of that section,
    and correlate with release dates, and then hope that the person
    writing was up-to-date.  That's -waaaay- too much work for a
    rather inaccurate return.)
(c) Thus, stuff on a wiki tends to get obsolete without anyone noticing.
    If it doesn't mention a version number, a new reader is never
    quite sure if it applies, or was simply overlooked.  And nobody
    but an expert can -fix- it, because they don't know if it's
    talking about some version they don't understand!

This is exactly the problem with trolling the mailing list archives,
but worse, because at least the archives have dates and (often) an
exact version specified somewhere.  It's still annoying because a
search can pull up many versions that have to be sorted through by
hand (thus making search useless after a while), but at least it's
there.  On the wiki, OTOH, things start out just -great- (because
there's only one version everybody's talking about) and then decay
into a bigger mess than the archives after there've been a few
versions released.  (If people are diligent about keeping every
page fresh---which at least they -can- be, unlike the list archives,
which by definition are frozen---then it -could- be better, but it
depends on this happening, and a new user has no way to know for
sure.)

Thus, -every- statement on the wiki would be improved by knowing what
version it's for.  If we adopted some relatively inobtrusive way to do
that such as by having a pastel background behind -every- paragraph,
whose color changes with release version (I'm -sure- somebody can come
up with a better idea---this is just a straw man), then every time
somebody updated the wiki, they would be also including version
information.  If they decided that they're going to rewrite a pale
pink (0.18.x) paragraph to reflect 0.19, they should just copy it,
change it to pale green, and edit -that-.  If some further edit
changes it to 0.20, the new editor can copy -that-, change its
background to pale blue, and proceed.  But -no- older versions
are being discarded -just because it's different in a new version-.
(Note that we -are- still silently updating wrong/incomplete info for
any given version---that part of the history is being obscured unless
you look in the edit history of the page---we're just not silently
rewriting/removing information that's correct and still valid and
whose only problem is that it doesn't reflect the latest version
from SVN.)

[Speaking of SVN---such things should probably have a distinctive
color -and- a precise version number that's actually stated.
Otherwise, users who run non-SVN versions will be shafted.
When a release happens, it should then be a simple matter to
simply declare that -that- color is the color of -that- release,
and maybe remove the exact SVN version numbers (or just leave
them there, since they're not harming anything if the readers
understand that (say) light purple is the color of 0.21).  Obviously
there needs to be a prominent color key on the homepage, no matter how
we do this.]

This has a number of advantages:
(a) Things which haven't changed since 0.18 (say) are obvious.
(b) Things which have multiple different behaviors make it really
    clear which version is being talked about.

It might also be nice if there was a way of saying "new" vs
"superceded", e.g., if you do the copy-recolor-edit thing, maybe the
new box gets a funny border, whereas new text doesn't.  That might
make it easier to figure out, given a green box, whether it's
superceding the pink box just before it or whether it's brand new.

Such color-coding (and border decoration) also makes it really fast to
sweep through the site and collect a relatively consistent set of
edits for -just- that version, if somebody wanted to do that.

Note that coloring pages by revision is exactly what's done in, e.g.,
hardcopy scripts during shooting, so people are quite literally sure
they're all on the same page... :)

[Another way to do this is to simply duplicate any page that has
version-specific info whenever the version changes, and make sure that
-the entire page- has the right background color; that might be easier
for people to read, and it's probably no more work or even less work.
The problem comes in how we know what links to follow from page to
page.  I'd actually prefer the one-page-reflects-only-one-version
scenario (more compact, potentially less confusing), but -only- if
we had some clever way of dealing with links.  (Redirects? Some
whizzy mechanism I'm not thinking about?)  One way to do the system
of completely-parallel-pages might be to copy&fork the entire part
of the wiki w/version-specific info at release time---there's always
the "SVN" fork, which just gets renamed into, e.g., the 0.20 fork,
and then that immediately gets copied into the "new" SVN fork and
people make edits there as SVN evolves.  Meanwhile, the 0.18 fork,
which happened two years ago, still remains, although it's rarely
updated.  As long as every page carries a pointer to "current
released" and "current SVN" versions, readers of old versions can
know where to go for current information, without losing info for old
versions they may still be running.  Again, this only works if the
"copy&fork" operation can handle links correctly.]

[Perhaps we could just make -every- link have an implicit version
number, e.g., "20:Mythfrontend" or "SVN:Transcoding"; the fork
operation upon release then becomes an automated (scriptable) edit
that copies all current SVN pages temporarily, changes "SVN:Title"
into "21:Title", and then puts all the SVN pages back (still as SVN)
for later editing as the current SVN, e.g., it duplicates all SVN
pages and then renames one of the two copies' links to "21" so they
freeze and stop getting updated by people who are updating pages based
on what's SVN this moment.  Then we just need some toplevel pages
pointing to the root of each tree so users can find them.]

    > It could help if people know of discrepancies between versions to
    > highlight them, but otherwise provide a big bold notice that the wiki
    > info may not necessarily apply to other versions of MythTV.

    > Since the majority of users will be running the latest, greatest
    > stable release I think it's only fair.  It's one thing to ask people
    > to contribute but quite another (much bigger job) to expect folks to
    > maintain multiple versions IMHO.

Assuming we do it right, the only effort that gets expended is when
people are writing stuff for the -current, new- version (assuming that
nobody every updates the wiki for any old version).  -That- effort
must happen anyway (or the current version will remain undocumented).
The trick is making sure that the -old- information---the stuff that
somebody already wrote last month about the old version---doesn't get
obliterated when the new information is added.  -That- is the whole
point of what I'm saying above.

The -worst- case is when it's never clear what version a page refers to
and users are left scratching their heads---or unable to find relevant
info for something they're still running because somebody overzealously 
edited a page describing the current release to instead describe the
current SVN (for example).