Re: confusing documentation
Andy Saxena <ansaxena@engr.uconn.edu> writes:
> This is specifically with reference to
> http://www.debian.org/doc/FAQ/ch-ftparchives.html#s-codenames
>
> "When sid did not exist, the FTP site organization had one major flaw: there
> was an assumption that when an architecture is created in the current
> unstable, it will be released when that distribution becomes the new stable.
> For many architectures that isn't the case, with the result that those
> directories had to be moved at release time, chewing up lots of bandwidth."
Having caught up on my email, and following this thread, I can
understand the confusion here.
The first sentence is almost 40 words long. The entire answer for this
question presupposes a lot more knowledge of Debian than is necessary.
In fact, I'd argue that the answer is given completely
backwards. Here's my suggestion for a rewrite:
If the word "architecture" means something different from the CPU's
instruction set, then this should be addressed in another FAQ. As far
as I'm concerned, "x86", "ppc", etc. are architectures. If it includes
the OS, ("x86-linux") that needs to be made clear.
Here's my suggestion:
| 5.7 What about "sid"?
|
| Sid will never be released. Before the creation of package pools, sid
| was a mix of released and unreleased architectures. (See What's in the
| pool directory? Section 5.13) (See What's an architecture?, TBD)
|
| Packages are now fed from unstable, to testing, and finally to stable.
| Sid is now synonymous with unstable.
The rambling detail about the history of the packaging system is
unnecessary to understanding sid what sid means *now*.
I'd even argue that sid shouldn't be around (if it still is), since it
now seems quite thoroughly obsolete.
I'm neither a Debian developer (Put myself into the queue a while ago,
got an email back over a year later. Heh. I get faster responses from
the financial aid department at my university.) nor do I have access
to CVS, so someone else will need to make this change.
While I'm at it, I'd like to take a moment to make a suggestion, to
anybody that wants to contribute to documentation. This is a
suggestion from Theodore Tso posted to debian-devel a few weeks ago:
http://lists.debian.org/debian-devel-0107/msg00446.html
> On Thu, Jul 05, 2001 at 03:42:10PM +0200, Joost Kooij wrote:
> > The problem is when people do not even know about dpkg anymore. When
> > they don't know about dselect (or any of its announced alternatives) or
> > its purpose. It implies that they are unaware of the essences of the
> > debian package management system. That worries me a lot more than the
> > package format adopted by some committee.
>
> You shouldn't be surprised. Read the Installation Manual, and you'll
> see that dpkg isn't even mentioned. Dselect is mentioned, but as
> something which is hard to use (which is true, for new users). The
> only Debian package management system which is mentioned is apt-get,
> and then only in passing. Even apt-cache isn't mentioned, which is a
> pity, since it's such a useful tool.
>
> One of the problems with Debian is that is that it has lots and lots
> of layers: apt-cache, apt-get, dpkg, dselect, dpkg-reconfigure,
> dpkg-deb, debhelper, debconf, etc. This wouldn't be too terrible a
> problem, except that there's no good overall documentation about how
> the various difference pieces interact, and how various different
> tasks should be accomplished. All the information you need is
> *somehere* in hundreds of man pages. But how the various pieces
> connect together is something which is passed on only by oral
> tradition, as near as I can tell.
>
> For example, it was a quite a while of my using a Debian system before
> I even *discovered* the existence of apt-cache, and then only because
> a friend of mine who was a Debian developer mentioned it to me. I
> similarly stumbled over dpkg-reconfigure. Before then, I had
> absolutely no clue how to get back to package configuration screens if
> I wanted to change things. (There's no mention of dpkg-reconfigure in
> any of the obvious manual pages. As far as I know, you simply have to
> be lucky and find it while investigating something completely
> unrelated, or be a mind reader.)
>
> If you want to fix the problem about people not knowing about dpkg,
> then someone needs to write a high-level document which explains all
> of the different layers and byways and programs and historical
> accidents (which is why dpkg-reconfigure isn't dpkg --reconfigure, so
> I understand) which are available in Debian, and how they interact,
> and how commonly available tasks which a system administrator might
> want to do can be most easily accomplished. Then, link it to the
> "Getting Started" section of Debian Web page.
>
> Someone might also want to think about improving the Installation
> Manual, which is supposed "suitable for new users". In particular,
> section 8.2, "Orienting yourself to Debian", is particularly weak.
> Try to put yourself in the mindframe of a new user who has no idea
> about the ins and outs of the Debian package management system (even
> if the new user has over 15 years of experience with Unix), and then
> read that section, and weep. (Or gnash your teeth in frustration,
> which is what I did.)
>
> - Ted
I strongly agree with this statement in the signature of this message:
"dselect has a user interface which scares small children"
I use "apt-get install" for installing new packages. I didn't realize,
until reading this thread, that it wasn't the best way to do it. If
dselect is the only way to do that, there's a big problem.
dselect needs to be replaced and the documentation needs some serious
work. I'll be the first to agree that the debian package system is
better than RPM, but if the tools and their interfaces don't make
sense, it won't make *any* difference to the typical user. It's mostly
out of laziness that I haven't installed KRUD yet.
</rant>
--
Chris Riddoch | epistemological
socket@peakpeak.com | humility
Reply to: