[mythtv-users] CVS
Ray Olszewski
ray at comarre.com
Wed Sep 3 09:17:57 EDT 2003
At 08:53 AM 9/3/2003 -0500, Robert Kulagowski wrote:
>>Oscar pointed out that it was in the docs, which I have read. Of course,
>>not completely.
> >I skipped over the section that read "How to obtain this document",
> because I was
> >already reading this document. So, to save someone else the frustration
> that I encountered,
> >I'm requesting another section for the CVS info or renaming the section
> title so that it is
> >more apparent.
>
>I'm not sure how much more apparent I can make it:
Then try this:
There are three ways to download the components of MythTV.
1. As a tarball. To do this, go to www.mythtv.org, select "Downloads", then
"MythTV", then "MythTV" again. This last step will cause the current
tarball to download.
2. From CVS. To do this, you need to be running the cvs program on your
host. Once you are, follow this procedure:
$ mkdir mythtv
$ cd mythtv
$ cvs -d :pserver:mythtv at cvs.mythtv.org:/var/lib/mythcvs login
Logging in to :pserver:mythtv at cvs.mythtv.org:/var/lib/mythcvs
CVS password: mythtv
$ cvs -z3 -d :pserver:mythtv at cvs.mythtv.org:/var/lib/mythcvs
checkout mythtv
This will download the latest copy of MythTV and the documentation from CVS.
3. As a prepackaged binary for your distribution. The MythTV Website itself
does not distribute prepackaged binaries, but it provides links to others
who do so for some Linux distributions. The links are located at this URL:
http://www.mythtv.org/modules.php?name=Web_Links&l_op=viewlink&cid=1
>v2.57, 2003-08-18. Add link back to CVS instructions from "Downloading
>and compiling".
>
>5. Downloading and compiling.
>
>Get MythTV from the mythtv.org web site. Save the tarball to a directory
>you can find. If you would like to run the CVS version of MythTV, follow
>the instructions located in the first section.
Your approach, Robert, has three problems as I see it.
1. It is sufficiently succinct that it is easy to miss. Wordiness is not
always a virtue, but sometimes it is, and I think this is one case where it
helps.
2. Directly below it is a much larger, and distinctively presented, "NOTE
for Mandrake users". This distracts the eye from the existing, brief
reference to CVS info.
3. It is a Band-Aid solution. "How to Get This Document" is a silly place
to locate the only instructions for accessing CVS. Adding a brief link to
that section in the right place (the beginning of Section 5) helps, but not
enough -- the information should be moved to, or at least repeated, in
SEction 5, where it belongs.
As a general matter, I would suggest being less defensive about comments of
the sort the original poster made. The point is not to "prove" that with
sufficient dedication, one can find the information. Reading the docs
shouldn't feel like solving a puzzle or playing a game. The point is to use
these comments as feedback that lets you identify areas where readability
(or Website organization ... I couldn't find a link from www.mythtv.org to
the page Isaac referred him to) needs improvement, then make the
improvements that are indicated.
Back when I was using MythTV, I tried to do this myself ... sometimes
successfully (e.g., the revisions I wrote to Chapters 3 and 4 ... at least
I hope I improved readability there), other times not (the draft Beginner's
FAQ that went nowhere except the list archives). When I stopped using Myth
(for reasons unrelated to documentation), revising its docs ceased to be a
priority for me. Nonetheless, I hope you will find the short draft above of
some use.
More information about the mythtv-users
mailing list