[mythtv-users] Re:MythTV Help Website

[Maarten van den Berg]

On Thursday 15 April 2004 06:56, Dan Conti wrote:

> > Subject: Re: [mythtv-users] Re:MythTV Help Website
> >
> > O M G !!
> > This just further proves the need for a wiki.  Let's see what
> > happened here,
> > shall we ?  Some enlightened souls suggest using a wiki, saying
> > that looking
> > through ML archives and google just isn't very productive nor handy.
> > Someone also remarks that still way too often people are referred
> > to "search
> > the archives, use google" as answers to their questions.
> >
> > ...And lo and behold, what is the answer to "let's install a
> > wiki" ? yep... :(
>
> Well what do you expect? For everyone to just snap to attention and
> reanswer the same question again? Keep in mind that most of the questions
> that get answered here either get answered once, or like 300 times.

Precisely!  And this fact is the single, strongest reason to deploy a wiki !!
When the answers are there for everyone to find, the flood of messages on this 
high-volume list will drop significantly. Everybody will be happy.

And, you gotta appreciate the irony in the answer to the OP.  ;-)

> > On a personal note, I vote for a wiki. I find that the current
> > docs are indeed
> > lacking, especially more so if:
> > * You're NOT using a PVRx50 card
> > * You're NOT located in the US
> > * You're NOT using one of the featured distributions.
> >
> > I've had enough experience with the above to contribute something;
> > documentation.  And there are better forms than searchable ML archives.
>
> You are making some assumptions here, such as 1) someone will invest the
> time to keep extensive documentation current, 2) people will actually read
> the documentation, etc.

I cannot speak for anyone else, but I sure read the docs. It is only when you 
realize that mostly, the docs for an OSS project are either nonexistant or 
just inadequate that you tend to skip that and run to google. I can name SO 
MANY projects that simply cannot be made to work with the official docs, it's 
just not funny anymore. Mind you, Mythtv does not fall in this category !

In fact, in some aspects the Mythtv docs are SO good that I got burned for 
asking about a feature that is documented even before the code is released 
(it's still in cvs right now).  That is  g r e a t  in one way, and meantime 
highly confusing in another...

> But the truth is that people dont read the documentation. 80% of the
> developer posts on this list end up being hyperlinks to places in the docs
> where obvious questions are answered. And there are limits to how extensive
> the documentation can be; just keeping it to a limited set of distributions
> is a task in and of itself, since there are a significant number of
> dependencies for this project. Trying to keep on top of all the
> distributions and all the variations between versions would be a nightmare.

Sure thing. But, all the more reason for a wiki.

> I urge you to consider your issue from the view of those who are on the
> providing end here. It's nice that you are offering to help, but you have
> to understand that these are empty words until you start providing patches.

Slashdot featured a couple of discussions on this subject very recently. I 
will not reiterate all that, but the essence of it centered around 
documentation and usability and hostility against non-contributers, even if 
they had great ideas to contribute ("well, we are happy to get your patches, 
but until you submit them please shut up") 
Very interesting discussions, and insightful from both sides...

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)   

Also, a wiki works just like a mailinglist in that you get feedback. Someone 
will correct you if you have made an omission, someone will fill the blanks 
where you lack the knowhow. Patches do not work that way. They must be clear, 
well written and without error, from the onset.  And they must not break the 
conventions and setup of the documentation already in place.  Surely, not a 
task you can give to just anyone ?

Some people have great ideas but they cannot write one coherent sentence. Some 
people can write, but as they have nothing to work with as real info it just 
drowns as / in chatter on the mailinglist. Some people can't code themselves 
out of an infinite loop but are great explaining stuff to peers. And some can 
code incredible stuff but have limited people skills. 

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.

As coders, you just can't imagine how big a hurdle it is for 'ordinary people'
to hear that they have to learn, for example, XML before they can join in.

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.

Unluckily, for most people there is only a short timespan where they will 
contribute docs: It is when when they _just_ surmounted an obstacle. But give 
it a couple of weeks and they will think back "how could I have struggled 
with something so trivial" and skip documenting (or fixing) it.  
At least, that is what I often observe...

Regards,
Maarten