Re: Re^2: directory structure - 2.
Hi,
>>"Marco" == Marco Budde <Marco.Budde@hqsys.antar.com> writes:
Marco> ? I#ve posted already such a list.
And there were objections to it, which have not been resolved.
CS> maintaining the list! If the list has evolved and is ready, it
CS> should become part of the doc-base documentation.
Marco> ? No it should be part of the Policy or a free standard. This
Marco> structure will not only used by doc-base.
That is really going aainst precedent. The add on modules to
the kernel and even kernel packages themselves follow a policy that
belongs to kernel-package. Emacs add-on packages foolow a policy laid
out in the emacsen-common package. The SGML packages follow a entity
management policy detailed in sgml-base.
CS> 1. Most people seem agree that documents should to be registered
CS> in several sections at once. This should be considered when
CS> setting up the structure.
Marco> Most people? Let#s stop this discussion. At first we should
Marco> talk about the structure and the file format. The use of the
Marco> system should be discussed in debian-devel.
Why shouyld we stop this discussion? You are the only one
objecting, and you have really come up with no technical reasons
apart from "I do not like it", which, frankly, does not cut it.
How can we come up with a structure before deciding on whether
we should or should not allows multiple listings?
Also, debian-policy is the correct forum for this discussion,
not debian-devel. This is Documentation Policy. debian-devel shall be
informed of the results.
CS> 2. For now, I think we should use the section titles in our list
CS> (like
Marco> I disagree. That#s confusing.
What is?
CS> make it much easier for us to recognize the correct section for a
Marco> We will not discuss the section for a document. This should be
Marco> done by the maintainers of these documents.
Oh, for gods sake, we are not talking about sections *of* a
document here. We are talking about categorization and classification
of documents.
Why am I getting the feeling that you are objecting for the
sake of objecting? I do not think that this is conducive to a
cooperative design.
CS> document. If we've finally agreed on the section titles, we can
CS> look for the correct short terms later.
Marco> I prefer the other way.
Preferences are irrelevant. Reasons, man, technical reasons.
CS> Ordering documents into categories like "howto", "faq",
CS> "magazines", "debian", etc. (categorized by source) is definitely
CS> *not* user friendly!=
Marco> I disagree 100%.
Without reasons, that matters little. As a user, I care little
about how documentation is arranged. I knwo I am looking for a list
pf magazxines that came with the system, or for what we have for
games, and how to configure sound ot my fax server.
Why should I care whther this is a ``user'' activity or a
``admin'' activity?
CS> 7. I think it's useful to already include a few example documents
CS> in the structure to get a better feeling about what will go into
CS> which section.
Marco> I disagree.
I think I like the example documents, for that helps make the
dry language of a standard more easily accesible. I would be lost in
the SGML handbook without the copious use of examples, and even
documentation policy shall benefit from it.
CS> language. I think the only logical way to handle this situation,
CS> is to store documents of all languages in a single structure, and
CS> let the user choose the preferred language at document-level, like
CS> in this example:
CS>
CS> User's Manuals Office applications _StarOffice User's Manual_
CS> (English version, German version)
Marco> I disagree 100%.
As I said, opinions are irrelevant. I like this single
structure idea, at least until we have fleshed out the documentation
in all supported languages. English seems to be the language of
choice for a vast amjority of the documents, and thus other languages
the document tree shall have a skeletal look. Also, until we have all
documents all cross translated, a multilingual user shall have to
search all possible languages until they hit the language tree that
has the documentation. It is frustrating to look in German first
since there are fewer documents there, and then go to english;
looking at english first means I miss out on my preferred language.
A single structure shall allow me to look simpley and select the
requisite language.
This works even if I am looking at docs using a fvwm menu, or
a simple non-locally-cross-indexed HTML tree.
See? technical reasons. Not opinions.
manoj
--
New York is a jungle, they tell you. You could go further, and say
that New York is a jungle. New York *is a jungle.* Beneath the
columns of the old rain forest, made of melting macadam, the mean
Limpopo of swamped Ninth Avenue bears an angry argosy of crocs and
dragons, tiger fish, noise machines, sweating rainmakers. On the
corners stand witchdoctors and headhunters, babbling voodoo-men --
the natives, the jungle-smart natives. And at night, under the
equatorial overgrowth and heat-holding cloud cover, you hear the
ragged parrot-hoot and monkeysqueak of the sirens, and then fires
flower to ward off monsters. Careful: the streets are sprung with
pits and nets and traps. Hire a guide. Pack your snakebite gook and
your blowdart serum. Take it seriously. You have to get a bit
jungle-wise. Martin Amis, _Money_
Manoj Srivastava <srivasta@acm.org> <http://www.datasync.com/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: