discuss: Removing the RCS/CVS HOWTO for review
Subject:
Re: Removing the RCS/CVS HOWTO for review
From:
"Chr. Clemens Lee" ####@####.####
Date:
12 Nov 2003 19:42:29 -0000
Message-Id: <1068666154.27099.74.camel@gavrilov>
Hi all, John,
curious from all the talk about how bad the al dev stuff really is, I
took a peak at the cvs doc. I must say, it isn't soo bad. All the basic
update, commit stuff etc. is described. When having the choice between
no document and that one, I would vote for the second option.
So if you want to remove it, I suggest someone writes a better
replacement first. I also wouldn't mind to have the choice between 3 or
more different documents covering a similar topic (as there is also a
document covering only RCS on tldp).
Further more if people use google searching for "cvs howto", guess what,
the tldp howto pops up on the number one spot. I am sure I haven't
linked to the cvs doc, but I assume some people must have done so, or it
wouldn't have gotten to the top. This shows at least some popularity.
There are other cvs howtos out there that didn't get the number one
spot. So I am not sure if removing the cvs document would do the linux
documentation project any favour (or any people looking for cvs help).
Just my $0.02,
Clemens
P.S. Unfortunately when I was in need to brush up my cvs knowledge
lately I remember I googled for "cvs tutorial" and therefore missed the
tldp cvs document back then. Otherwise I would have gotten the first
hand experience of how useful that document really is.
On Wed, 2003-11-12 at 03:15, John Levon wrote:
> Here is a short critique of
> http://www.tldp.org/HOWTO/CVS-RCS-HOWTO.html, giving reasons why it
> should be removed for review from the LDP, as is policy.
>
> If this needs the attention of a specific person, could somebody at the
> LDP make sure they are notified ?
>
> There are many misleading and curious statements peppered over the docs.
> To pick one example:
>
> "It is very strongly recommended that you use CVS, because you can
> greatly customize CVS with scripting languages like PERL, Korn and bash
> shells."
>
> Whilst it's certainly sensible advice to suggest CVS over RCS, this is a
> rather odd reason. AFAIK I do not see any reason why you cannot script
> RCS operations too.
>
> "# Very highly sophisticated and complex system. It is "State of the Art"
> # technology. The cvs software is a very advanced and capable system
> # developed over a very long period of time (it took several years!!)"
>
> Opinion without sensible rationale in a HOWTO should be discouraged.
> It's also inaccurate as anybody with a little knowledge about source
> control systems will know.
>
> It refers specifically to installing RPMs on Red Hat. Since this process
> is trivial and well documented elsewhere, I do not see why it belongs in
> the HOWTO at all. HOWTOs should aim to be concise and readable.
>
> "The following environment variables need to be setup in /etc/profile -
> default values required for all users."
>
> Not true at all, this is merely one way to arrange things, and not
> necessarily a sensible one.
>
> "Intro to CVS commands"
>
> This simply pastes the command line help, with little added value above
> that help itself and "man cvs".
>
> "Shell scripts"
>
> This section appears to be advertising (apparently trivial - see
> "supdate" description) code available for a fee from the author. I don't
> know what the guidelines say about this, but I find it to be unfortunate
> at best.
>
> After this, there a few links. The links may well be useful, but not
> useful enough to form an LDP HOWTO in my opinion. Similarly for the list
> of CVS GUIs. There is no added-value information, for example, a
> comparitive review of available software and their relative merits.
>
> Chapter 9 covers CVS on MS Windows. Sometimes information on other
> platforms is useful (a good example being the NAT HOWTO). I do not think
> it's suitable here. Furthermore, there are digressions into VNC and
> window managers, which is clearly not on-topic.
>
> Chapter 11 covers CVS authentication setup and configuration. Whilst
> this chapter is somewhat better, the stuff is well-documented in several
> places elsewhere.
>
> Chapter 13 has no CVS-specific performance tuning information
>
> Chapter 14, apart from being very short, would be better in a
> Project Management HOWTO. Chapter 15 similarly digresses into stuff not
> covered by the remit of the HOWTO. Good HOWTOs focus on one specific
> subject and keep to it.
>
> Chapter 17 does not give enough information RCS vs. SCCS to be able to
> make a useful judgement.
>
> In summary, I believe this HOWTO should be removed for review for the
> following reasons:
>
> o HOWTO does not contain sufficient value-added information beyond other
> help resources
> o the list of links is bare (no comparative information)
> o the HOWTO spends a significant amount of text advertising trivial
> non-free software
> o the HOWTO digresses too much into other subjects (such as compiling
> things on Solaris that have nothing to do with CVS)
> o the HOWTO is poorly written in terms of grammar and style
>
> regards,
> john
>
> ______________________
> http://lists.tldp.org/
>
