discuss: Removing the RCS/CVS HOWTO for review
Subject:
Removing the RCS/CVS HOWTO for review
From:
John Levon ####@####.####
Date:
12 Nov 2003 02:15:04 -0000
Message-Id: <20031112021503.GA48141@compsoc.man.ac.uk>
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
