[mythtv-users] Re:MythTV Help Website

[Maarten]

On Thursday 15 April 2004 12:22, J. Donavan Stanley wrote:
> Maarten van den Berg wrote:
> >On Thursday 15 April 2004 06:56, Dan Conti wrote:

> Semi OT:  I've never seen a wiki that was worth a crap.  Care to share a
> couple links?

Sorry. I'm not up to speed on that.  Are you really saying they're all crap ?

> >And, you gotta appreciate the irony in the answer to the OP.  ;-)
>
> Searching the mailing list archives or using google for an OSS project
> should be considered the equivalent of reading the help file of a
> windows app.  That's just how things work.  The folks that come here
> asking questions that are easily answerable are the same folks that call
> tech support before reading the help files.

True. But searching mailing lists is a royal pain, mostly.  I oftentimes 
subscribe so I can use my native tools to search for answers in a couple of 
weeks, instead of having to use web archives. But then, you always miss 
previous stuff.
But I think that we should not stop and say "That is how it's been done for 
centuries" but keep open minds for any possible improvements. 

> Again, I'd have to see a wiki that works but every one I've seen is full
> of holes, wrong information and useless info that it's impossible to
> find anything useful.  The exception to that has been the various
> "definition" sites that have a very focused scopes.

My experience with wiki is limited, sure.  Of course, if we're shifting the 
subject from the yes/no question to how to implement it, there are tons of 
issues.  I think that is not very relevant at this time. Dunno what is out 
there, but maybe posts can be moderated, either in the original sense or in 
the slashdot model where you can promote or demote a piece to keep it tidy.
Or maybe I'm totally confused about how a wiki works.  I just would like 
<something> that lies in between a forum / ML and a html/sgml site.  

> >Now, back to this. I feel that there is a VERY big difference between
> >requiring sgml patches, or having a low-threshold wiki. Let's say I wanted
> > to correct or annotate 1 sentence in the docs. Send patches ? Yeah, very
> > likely. No, just like everybody else, I just assume that it being
> > corrected on the ML is enough, and that maybe even someone already
> > compiles a faq out of ML answers. (when you are new you have no way to
> > know how it currently is done)
>
> Now we've switched gears here... A little bit ago folks were talking
> about adding large amounts of documentation not correcting things here
> and there.

Yeah, stuff depends.  Sometimes you might want to devote an entire chapter to 
something, and yet sometimes adding "if using distribution Foo, add 
--include-bttv_alsa to your ./configure flags"  will be quite enough help.

> >Just like with coding, people are reluctant to be made fun of for making
> >mistakes, be it typos, awkward sentences, misinformation.  A wiki is a
> > good way to lower the threshold people have to step over to contribute.
>
> That makes little sense to me.  If you submit a patch to the docs a
> couple of people will bother to apply, read it  and give feedback.  If
> it's on a Wiki it's out there for everyone to see and ridicule.

A wiki seems like a good way to include the "consensus" of a ML thread into 
some form of semi-official documentation. Don't you wish that some of the 
threads here would be summarized at the end and included somehow ? 
Yet no-one takes that time (unless I missed that). A wiki would automate this 
entire process. I think. 
As always, if someone says a stupid thing it will still be a stupid thing. :-)

> >The way it works for me -and a lot of others, I presume- is like this:
> >First, you have tons of questions (you're a newbie!) and can't offer
> > anything back as you're struggling yourself. Then, having found out some
> > things, you think "may be better to lurk on the ML a couple of weeks
> > first" to get yourself an idea of how things are done in this project.
> > You don't yet feel "ready" to contribute, as you think you may not know
> > enough yet. But then, after a while, you progress, and you may get
> > interested in other projects. You tend to forget the problems you
> > struggled with, once you overcome them.
>
> But the million dollar question is:  "Did you need to struggle with that
> problem?"  i.e. if you had: Read all the docs, searched the mailing list
> & used google would you have found the answer in a reasonable amount of
> time?

Nice, in theory, but irrelevant in practice, IMHO.  I've installed a LOT of 
things over the years, and invariably you will have missed some info.
Either by skipping over it reading too quickly, or by not re-reading a chapter 
for a second time that has both beginners- and experts' information in it.

I don't have the slightest idea what you have experience with, but for me, 
forgetting or omitting real simple things happens all the time. There have 
been countless times where I read a manpage and did not understand how to 
work a tool.  Then later, after you mastered it, if you re-read that same 
manpage it all makes sense to you but it didn't _before_ you knew it.
There is a difference having all the information scattered all over the 
internet and having it all in one or two places.

I often compare it to having an empty config file (having to google all the 
time for options and syntax) versus having a fully inline-documented config 
file with all options in it but commented-out where applicable.  I can work 
with both configs, but I assure you that the latter takes me minutes and the 
former might take me the better part of an evening if things turn bad.

Sometimes, solutions are SO obvious yet SO damn hard to find. Case in point; a 
very long time ago I had this problem with my browser getting killed after a 
couple of days for no apparent reason on one system, and behaving flawlessly 
on another identical system.  This happened even when not even touching the 
window(s). I pulled my hair in frustration since I could not for the life of 
me figure it out.  Eventually I found the culprit: In a somewhat overzealous 
mood, I had inserted some high 'ulimit' statements in /etc/profile.  As it 
happened, Netscape was the first program to hit those limits -> it was known 
for its bad memory-leaks, and the shell just killed the process then.
As will be obvious, this type of problem is rather unsolvable through Google.

> Personally, I think what Myth needs more than a Wiki is a FAQ and even
> that could be rolled into the howto I think.  I'm not saying a wiki is a
> horrible idea, I just question the usefulness of adding another
> information source when the existing ones aren't being used properly.

Well, sure, good idea. But who will compile that faq ? And if a faq maintainer 
stands up, will he not also ask of the would-be contributors to submit sgml ?
Then we will have the same threshold as we do now.

Maarten

-- 
Linux: Because rebooting is for adding hardware.