discuss: Re: book vs article (vs HOWTO vs GUIDE and other implications)
Subject:
RE: book vs article (vs HOWTO vs GUIDE and other implications)
From:
"Patrick K. O'Brien" ####@####.####
Date:
12 Mar 2001 19:06:56 -0000
Message-Id: <NBBBIOJPGKJEKIECEMCBIEGOJJAA.pobrien@orbtech.com>
Whack me with a flounder if you're tired of me carping about this <g>, but
I'm just really perplexed by this whole attempt to distinguish help
documents according to their size and complexity. I think it is a losing
battle and an immediate source of annoyance for anyone who is simply trying
to find a solution to their problem. I find it hard to believe that any
reader really cares whether a document is a HOWTO, mini, guide, book or
other. They just want information.
So what exactly is my problem? My concern is that this classification scheme
permeates the entire LDP, making it very inflexible. Take the directory
structure, for example. Here is a typical link to a HOWTO -
http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/3Dfx-HOWTO.pdf
. Now here are the problems that I see. (Take this rant with a grain of sea
salt, but I really feel the need to vent.)
1. What happens if you want to reclassify this as a guide or a mini?
Obviously the directory path would have to change. So you change the path
and break every link to this file that exists in every other document, other
websites, printed books, etc. Ouch!!!
2. What happens if the user decides they want to get this document in some
other format? Can they back up the hierarchy and get the other available
formats for this particular document? No. They either have to figure out
what the "other formats" are that are listed at
http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ and find their
document again, or they have to go to the LDP home page and drill down
again. Basically, the directory structure does not really lend itself to
useful navigation by an average user of the site. (For all I know it might
be the cat's pajamas for the maintainers of the site, but they are not my
concern in this rant.)
3. What are we "teaching" the community by organizing the documents this
way? We are teaching them that these are the most important criteria for
finding and distributing helpful documents. That the HOWTO vs Guide vs Mini
vs FAQ issue is really, really important. That new users who have a problem
need to be able to understand and appreciate the subtle nuances of this
classification scheme. That just because you've found the html pages for a
document doesn't mean that it will be easy to find the pdf version without
understanding this classification scheme. That size really does matter.
(Whack! Okay, I'll stop there.)
What would I suggest?
1. Change the LDP directory structure to be completely flat or at least
topical. I doubt that there are any duplicate names that would conflict if
you put all the files in the same directory. 2. Replace all the existing
paths with redirectors to point to the new locations so that existing links
do not fail. 3. For each document, have an html page that gives a brief
description followed by links to every format in which the document is
available. 4. Build index pages (preferably dynamically from a database) and
provide search capabilities to "partition" or "group" the list of documents
according to criteria relevant to each individual user. (I know, the plan is
to go to scrollkeeper and omf, but I'm impatient and nobody has talked about
changing the directory structure.)
The organization of these documents has to be as flexible as possible.
Documents should be able to grow and mutate. A Mini could grow to a Howto
and later to a Guide. A Guide might just be a consistent set of Howtos by
the same author. A single page from a Guide is indistinguishable from a Mini
in the eyes of the average reader, imho. The LDP should reflect that. Isn't
that what DocBook is all about? One source, multiple formats. We need to
apply that same attitude to the organization of the documents as a whole.
Rebuttals?
P.S. Apologies to anyone I might have rubbed the wrong way. I just wanted to
air this issue. My goal is to help make the LDP better, not to impugn the
work that has gone on to date.
---
Patrick K. O'Brien
Orbtech (http://www.orbtech.com)
"I am, therefore I think."
-----Original Message-----
From: David Merrill ####@####.####
Sent: Monday, March 12, 2001 11:21 AM
To: ldp-discuss
Subject: Re: book vs article
<snip>
Since afaik size is the determining factor for whether a document is
classified as a Guide or a HOWTO, perhaps those HOWTOs should be
reclassified as guides, and the article=HOWTO, book=guide distinction
then makes perfect sense.
Of course it isn't purely a raw size issue; complexity matters, too.
The Consultants HOWTO, for example, is a very large document but not a
very complex one.
--
Dr. David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Collection Editor & Coordinator http://www.linuxdoc.org
Finger me for my public key
As of next week, passwords will be entered in Morse code.
_________________________
http://list.linuxdoc.org/
