Mailing List Archive: MythTV: Dev

MythTV Manual

Index | Next | Previous | View Threaded

mitchell.gore at gmail

Mar 19, 2008, 11:06 AM

Post #1 of 8 (982 views)
Permalink

MythTV Manual

Hello,

I have spent some time trying to update the documentation on the wiki but
have also noticed that there is documentation on the webpage as well but it
is outdated to .20.

This raises several questions:

1. Why is there 2 usermanuals?
http://www.mythtv.org/modules.php?name=MythInstall
http://www.mythtv.org/wiki/index.php/User_Manual:Index

2. Can we consolidate them?
The wiki seems like a better solution as many people can update it breaking
the task into smaller projects.

3. If not, We should get rid of one to eliminate confusion.

4. If we are keeping the non-wiki version how can others, including myself,
get write access to help update.

Just trying to contribute to the project. I am not a coder and have heard a
thousand times we can contribute with documentation.

Mitchell

(WIKI ID: mitchell2345)

mtdean at thirdcontact

Mar 19, 2008, 1:26 PM

Post #2 of 8 (933 views)
Permalink

Re: MythTV Manual [In reply to]

On 03/19/2008 02:06 PM, Mitch Gore wrote:
> I have spent some time trying to update the documentation on the wiki
> but have also noticed that there is documentation on the webpage as
> well but it is outdated to .20.
>
> This raises several questions:
>
> 1. Why is there 2 usermanuals?
> http://www.mythtv.org/modules.php?name=MythInstall
> http://www.mythtv.org/wiki/index.php/User_Manual:Index

The non-wiki one is the one that's actually reviewed for correctness.
'nuff said.

> 2. Can we consolidate them?
> The wiki seems like a better solution as many people can update it
> breaking the task into smaller projects.

Perhaps a better solution is to have something like the MySQL docs in
the wiki. It contains a non-editable copy of the official docs with a
location for people to write in "notes". I don't know if it's possible
to do something like that with the wiki we're using. If not, perhaps
just having wiki pages with links to (or iframes or divs or ?
containing) the official HOWTO pages with "notes" underneath.

> 3. If not, We should get rid of one to eliminate confusion.
>
> 4. If we are keeping the non-wiki version how can others, including
> myself, get write access to help update.

Make a patch to mythtv/docs/mythtv-HOWTO.sgml and submit it with a
ticket on Trac. I thin Robert has also said he would accept text
written as plain text (but /no/ changes to the mythtv-HOWTO*.html files
and no HTML text).

> Just trying to contribute to the project. I am not a coder and have
> heard a thousand times we can contribute with documentation.

Thanks!

Mike
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev

rkulagow at gmail

Mar 19, 2008, 1:43 PM

Post #3 of 8 (936 views)
Permalink

Re: MythTV Manual [In reply to]

Michael T. Dean wrote:
> On 03/19/2008 02:06 PM, Mitch Gore wrote:
>> I have spent some time trying to update the documentation on the wiki
>> but have also noticed that there is documentation on the webpage as
>> well but it is outdated to .20.
>>
>> This raises several questions:
>>
>> 1. Why is there 2 usermanuals?
>> http://www.mythtv.org/modules.php?name=MythInstall
>> http://www.mythtv.org/wiki/index.php/User_Manual:Index
>
> The non-wiki one is the one that's actually reviewed for correctness.
> 'nuff said.

I didn't start the wiki version of the docs, and don't really have the
time to work on that sort of stuff and try to keep it up to date. The
wiki is good for some things, but also bad for others. There are how
many different versions of distro-specific install docs?

>
>> 2. Can we consolidate them?
>> The wiki seems like a better solution as many people can update it
>> breaking the task into smaller projects.
>
> Perhaps a better solution is to have something like the MySQL docs in
> the wiki. It contains a non-editable copy of the official docs with a
> location for people to write in "notes". I don't know if it's possible
> to do something like that with the wiki we're using. If not, perhaps
> just having wiki pages with links to (or iframes or divs or ?
> containing) the official HOWTO pages with "notes" underneath.

I'm not sure if this can be done, since I didn't setup the Wiki.

> Make a patch to mythtv/docs/mythtv-HOWTO.sgml and submit it with a
> ticket on Trac. I thin Robert has also said he would accept text
> written as plain text (but /no/ changes to the mythtv-HOWTO*.html files
> and no HTML text).

Yep, that's pretty much the process. Since the SGML file is used to
generate the HTML and the plain text docs, sending me something full of
HTML doesn't do much good.

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev

mitchell.gore at gmail

Mar 19, 2008, 4:44 PM

Post #4 of 8 (925 views)
Permalink

Re: MythTV Manual [In reply to]

> Make a patch to mythtv/docs/mythtv-HOWTO.sgml and submit it with a

> > ticket on Trac. I thin Robert has also said he would accept text
> > written as plain text (but /no/ changes to the mythtv-HOWTO*.html files
> > and no HTML text).
>
> Yep, that's pretty much the process. Since the SGML file is used to
> generate the HTML and the plain text docs, sending me something full of
> HTML doesn't do much good.
>

I guess i still dont see how the Wiki would not be better. Creating
tickets just to change a few things seems to envolved. Wiki changes are
simple and documentation could be updated faster. My though on the manual
is not to describe how to install Mythtv on X distro. But an explanation
for each settings/how to use it.

Mitchell

skd5aner at gmail

Mar 19, 2008, 5:41 PM

Post #5 of 8 (945 views)
Permalink

Re: MythTV Manual [In reply to]

On Wed, Mar 19, 2008 at 7:44 PM, Mitch Gore <mitchell.gore [at] gmail> wrote:
>
> I guess i still dont see how the Wiki would not be better. Creating
> tickets just to change a few things seems to envolved. Wiki changes are
> simple and documentation could be updated faster. My though on the manual
> is not to describe how to install Mythtv on X distro. But an explanation
> for each settings/how to use it.
>
> Mitchell
>

I don't necessarily think it's a good idea for official documentation
to be open to the masses. I couldn't see any technology company
releasing a product and saying "here's our documentation, it's on a
wiki, have at it." Probably best to stay the way it is by keeping it
as part of the application and submitting tickets/patches to update.

Thanks!
Matt S.
_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev

dean.harding at dload

Mar 19, 2008, 5:54 PM

Post #6 of 8 (925 views)
Permalink

Re: MythTV Manual [In reply to]

Mitch Gore wrote:
> I guess i still dont see how the Wiki would not be better. Creating
> tickets just to change a few things seems to envolved. Wiki changes are
> simple and documentation could be updated faster. My though on the
> manual is not to describe how to install Mythtv on X distro. But an
> explanation for each settings/how to use it.

I think the problem with the Wiki, where it can be edited by *anyone*
(or virtually anyone), is that in the past people have written
"installation instructions" for the specific distribution they use --
typically the specific *version* of the specific distribution they use.
So you end up with pages like:

http://www.mythtv.org/wiki/index.php/Installing_MythTV_SVN_on_Debian_Sid
http://www.mythtv.org/wiki/index.php/Installing_MythTV_SVN_on_Fedora_Core
http://www.mythtv.org/wiki/index.php/Installing_MythTV_SVN_on_Ubuntu_Breezy
http://www.mythtv.org/wiki/index.php/Installing_MythTV_on_Debian_Etch
http://www.mythtv.org/wiki/index.php/Installing_MythTV_on_Fedora_7
http://www.mythtv.org/wiki/index.php/Installing_MythTV_on_Fedora_Core_VGA%26composite
http://www.mythtv.org/wiki/index.php/Installing_MythTV_on_an_Athlon64_using_Fedora_Core
http://www.mythtv.org/wiki/index.php/Ubuntu_Edgy_Installation
http://www.mythtv.org/wiki/index.php/Ubuntu_Feisty_Installation
http://www.mythtv.org/wiki/index.php/Ubuntu_Hoary_Installation

And so on, and so on...

Now, it's probably good that we have specific instructions for each
distribution that people may want to use, but there's also a few problems:

1. The instructions generally lack coherance. What I mean is, they
should be used to *compliment* the "main" installation instructions at
http://www.mythtv.org/wiki/index.php/User_Manual:Index. Often, though,
the distro-specific instructions attempt to fill in *all* the details so
you get lots of duplication.
2. Once people finish writing the instructions, they generally never go
back to it again. So they'll include instructions for 0.20 (some are
even stuck at 0.19 still).
3. Who the hell is installing Ubuntu Hoary or Edgy? Nobody deletes
out-of-date pages.

These problems could be solved with some dedicated editors for the wiki,
obviously, but I don't think the wiki has any of those, does it? I agree
that with proper maintenance, the wiki is probably the more flexible
solution, though. It just needs more work initially (and someone to keep
an eye on it). The benefit of having the "official" documentation under
source control is that you're basically forcing an "editor" to look at
it before checking it in.

Dean.

_______________________________________________
mythtv-dev mailing list
mythtv-dev [at] mythtv
http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev

myth at dermanouelian

Mar 19, 2008, 8:40 PM

Post #7 of 8 (931 views)
Permalink

Re: MythTV Manual [In reply to]

On Mar 19, 2008, at 11:06 AM, Mitch Gore wrote:

> Hello,
>
> I have spent some time trying to update the documentation on the
> wiki but have also noticed that there is documentation on the
> webpage as well but it is outdated to .20.
>
> This raises several questions:
>
> 1. Why is there 2 usermanuals?
> http://www.mythtv.org/modules.php?name=MythInstall
> http://www.mythtv.org/wiki/index.php/User_Manual:Index

Not sure, but I updated a bunch of screen shots on the wiki User
Manual and wouldn't mind doing a bunch for the official documentation
if that would help out. I imagine there's a better process for that
than opening a ticket for images as I get to them. If the maintainer
of that page wants some help with new screen shots, mail me off-list
to let me know how I should submit them.

-Brad

hoodlum7 at gmail

Mar 23, 2008, 12:40 AM

Post #8 of 8 (866 views)
Permalink

Re: MythTV Manual [In reply to]

Well the wiki is MediaWiki and I know from the same wiki I use at work the
admin can protect the page so nobody but admins can modify it. Also, for
each revision of the Article you can send out a permanent link. This may be
a way to track revisions of the Manual to differing versions of MythTV.
Then users can suggested changes on the Discussion page for the Manual.
There are also extensions to the Wiki in use to allow certain articles to
only be modified by certain groups of people.

On Wed, Mar 19, 2008 at 8:40 PM, Brad DerManouelian <myth [at] dermanouelian>
wrote:

> On Mar 19, 2008, at 11:06 AM, Mitch Gore wrote:
>
> Hello,
>
> I have spent some time trying to update the documentation on the wiki but
> have also noticed that there is documentation on the webpage as well but it
> is outdated to .20.
>
> This raises several questions:
>
> 1. Why is there 2 usermanuals?
> http://www.mythtv.org/modules.php?name=MythInstall
> http://www.mythtv.org/wiki/index.php/User_Manual:Index
>
>
> Not sure, but I updated a bunch of screen shots on the wiki User Manual
> and wouldn't mind doing a bunch for the official documentation if that would
> help out. I imagine there's a better process for that than opening a ticket
> for images as I get to them. If the maintainer of that page wants some help
> with new screen shots, mail me off-list to let me know how I should submit
> them.
>
> -Brad
>
>
> _______________________________________________
> mythtv-dev mailing list
> mythtv-dev [at] mythtv
> http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
>
>

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads