Re: directory structure - 2.
On Tue, 14 Apr 1998, Marcus Brinkmann wrote:
[snip]
> I would volunteer to maintain the
> list/structure/whatever-you-like-to-call-it. This means, I would collect
> suggestions, new entries etc and would post updated versions (if
> appropriate with alternatives) on this list. Probably this could avoid
> some confusing discussion on this list.
This sounds like a great idea! If noone else objects, please start
maintaining the list! If the list has evolved and is ready, it should
become part of the doc-base documentation. Until then, it would be great
if you could maintain such a list.
I've included a first proposal of myself below. Note, that this is just my
very personal opinion--feel free to change this if you don't like it.
Here are some other (very personal) notes: (the notes have no particular
order)
1. Most people seem agree that documents should to be registered in
several sections at once. This should be considered when setting up the
structure.
2. For now, I think we should use the section titles in our list (like
"Developer's Manuals"), not the short terms (like "devel"). This should
make it much easier for us to recognize the correct section for a
document. If we've finally agreed on the section titles, we can look for
the correct short terms later.
3. If the structure has evolved, all online menu systems (dwww and dhelp)
should use the same section titles, in order to avoid confusion among
users who use both systems or who switch from one system to the other.
4. My proposed structure uses two levels of sub-sections. I think that
this is a good default value, but it should also be possible to place
documents in a level-1 or even level-3 section.
5. We should keep in mind that the structure should make it as simple as
possible for the users to find the documentation their looking for.
Ordering documents into categories like "howto", "faq", "magazines",
"debian", etc. (categorized by source) is definitely *not* user friendly!
6. AFAIR, dhelp displays only `used' sections (i.e., sections which
contain documents). I think, in general, it would be better if the online
systems always display all available sections, even if these are empty, so
that the user knows where to look for documentation next time.
7. I think it's useful to already include a few example documents in the
structure to get a better feeling about what will go into which section.
8. We should keep in mind that the section titles will eventually be
translated into the user's native language. But for now, we should stick
to discuss the English titles.
9. Only very few of the manuals will be available in the user's native
language. I think the only logical way to handle this situation, is to
store documents of all languages in a single structure, and let the user
choose the preferred language at document-level, like in this example:
User's Manuals
Office applications
_StarOffice User's Manual_ (English version, German version)
The text "StarOffice.." will be a hyperlink to the default language, which
is English in this example. With default German it would look like:
Anwenderhandbücher
Office-Anwendungen
_StarOffice Handbuch_ (Englische Fassung, deutsche Fassung)
(I'm sure all the other German speaks have better terms for this now--but
the exact terms don't matter in this example here ;-)
Comments are welcome!
Thanks,
Chris
--
User's manuals [user]
Editors [user/editors]
GNU emacs manual
vim Manual
elvis manual
Games [user/games]
GNU chess user's manual
Graphics [user/graphics]
GIMP Introduction
Mail clients [user/mail]
elm manual
pine manual
Math/Scientific software [user/math]
pari manual
News clients [user/news]
trn manual
tin manual
Office applications [user/office]
StarOffice manual
Shells [user/shells]
GNU bash manual
ash
Sound tools [user/sound]
wavplay manual
Text processing systems [user/text]
tetex user's manual
debiandoc-sgml markup manual
Web clients and programs [user/web]
Mozilla User's Guide
htdig search engine
weblint
Developer's manuals [devel]
C documentation [devel/c]
libc6 documentation
Libraries [devel/libs]
GTK+ documentation
Perl documentation [devel/perl]
Debian's Perl setup
List of available Perl/CPAN modules
X Windows programming [devel/x11]
GTK+ documentation
xbooks
Administrator's manuals [admin]
Installation instructions [admin/install]
Debian Installation Manual
dselect Beginner's Guide
Debian Release Notes
Linux Hardware HOWTO
Debian's packaging system [admin/packaging]
dselect Beginner's Guide
APT user's manual
How Software Producers can produce .debs for their products
Linux Kernel documentation [admin/kernel]
Networking [admin/net]
PPP
SLIP
ISDN
Cable-modems
Routing/Firewalling
tcpdump
X Windows documentation [admin/x11]
Debian's X README
Setting up X...
Debian developer's documents [debian]
General [debian/general]
Debian Dictionary
Debian FAQ
Debian META Manual
Standards [debian/standards]
Debian Policy Manual
Debian Packaging Manual
Debian Developer's Reference
FSSTND
FHS
...
Package developer's manuals [debian/packaging]
Debian Packaging Manual
Intro: Making a .deb
Debian Menu System
General documentation [general]
Debian FAQ
Debian META Manual
Linux HOWTOs/FAQs [general/howto]
Linux META FAQ
...
Online magazines [general/magazines]
Linux Gazette
PLUTO Journal
L'Echo de Linux
-- Christian Schwarz
schwarz@monet.m.isar.de, schwarz@schwarz-online.com
schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
CS Software goes online! Visit our new home page at
http://www.schwarz-online.com
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: