[mythtv-users] Mailing list and a Wiki... and a dessert topping

[David]

Isaac Richards wrote:

> <snip>
>
>"If you would like to submit an update or contribution, please send it as 
>either SGML or as plain text."
>
>What are the last 2 words of that sentence?
>  
>
"plain text"
If you have to ask I can see why you're not so hot on this documentation 
thing ;)

anyway, after that attempt to lighten the tone and keep everyone friends...

First an apology: I am sorry for mixing up 'Docbook' and SGML in my 
attempt to recall the doctype.
My excuse is that the MythTV SGML docs use Linuxdoc which is at least 
related to Docbook - even the Linuxdoc FAQ has: 4. Comparing LinuxDoc to 
DocBook.

Next, why am I bothering?
Because I care (as do you); because I've put some effort into this and 
because I think we should at least respect each others viewpoint.
I have the new viewpoint so it's up to me to put together reasoned 
arguments - I'll try...

I think I understand your points:
* some good docs already exist
* users are confused enough and don't need more 'fly-by-night' sites 
with potentially out-of-date info
* the docs _can_ be changed - just submit patches

However my main points are:
* I _don't_ want to send an update to the howto or the docs
* I _do_ want somewhere to work on updates to the docs - but not on my 
own - I would like to encourage people to help

(I refer readers to my earlier post on 'feeding back to the core docs' 
being a frontpage objective - in case anyone things I'm trying to 
'split' the docs)

As BP recently said:

> Here's an idea:  you and others that wish to contribute documenation 
> could have a private wiki to work together on.  One of the people in 
> your group could be responsible for taking milestones, formatting it 
> in SGML and submitting a patch to Isaac against the offcial docs.  
> That would allow for those that are intimidated with the current 
> process to contribute yet keep focused on a single, official document. 

Except I don't see why it should be private - the dev-list and CVS 
aren't. In fact this is more like an 'anyone can commit' easy-CVS

> You might even start by importing the current documentation to your wiki.

It's a good idea - I though about it quite a bit - we'd need to keep in 
sync and it's too hard for now.
Instead I was hoping that (eventually) the official docs would link to 
wiki pages for 'comments on this FAQ'
Also I wanted to see the wiki get a little more accepted before doing 
things that could easily have been misinterpreted as usurping mythtv.org
Since you mention it though, look here:  
http://www.mythtv.info/moin.cgi/OfficialFaq ...... reasonable compromise?

Isaac (and Robert) - could you please take a look too and contemplate 
(not commit to - not yet) working with me/us on linking the FAQ to the 
Wiki like this? I don't expect an answer yet - I simply ask you to 
consider it.


Back to the original topic...
And since developers have CVS for the code - and this is the equivalent 
for the docs - maybe, if the wiki proves itself, MythTV.org could link 
to it as such?

If you look here:
  http://www.mythtv.info/moin.cgi/ArchiveToDvd
You'll see where I grabbed a couple of postings from this list and began 
to collate them.
I intend to do the same for ALSA/SPDIF (and I've already been 'marking' 
informative emails generally so I can do that kind of thing)

Docs are not like code - I can't compile and test them - I already know 
what they're trying to tell me so I'm a useless test subject.
I need to show them to others (preferably interested newbies - or even 
desperate old-hands) and get feedback (kinda like a compiler spitting 
back syntax errors)
Then they need to be tried in different systems to ensure that they 
cover boundary cases - I have two systems but that's not enough.

Would you accept any of those chunks of text as changes into 21.18? (and 
as Henk suggests - where would you stop? Do you intend to give 
instructions on using qdvdauthor to produce episodic DVDs? - I do - but 
only because I've just burnt about 30 Farscape DVDs for my wife and now 
know it inside and out)
Anyway (even disregarding the scope thing) - I think not - and rightly 
so - the docs are authoratitive reference material and the stuff on the 
wiki just isn't ready yet.
But they are now preserved - I've been busy - you're not the only guy in 
the world with job problems you know - and I (and indeed others) can go 
back to this embryonic work as the time becomes available.

Please see this effort  as the constructive attempt to help with MythTV 
that it is - MythTV has honestly changed my life for the better and I 
*really* do want to contribute back. Please give us a chance and be 
supportive.

David