[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: directory structure - 2.

On Tue, 14 Apr 1998, Marcus Brinkmann wrote:

> 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

 1. Most people seem agree that documents should to be registered in
several sections at once. This should be considered when setting up the

 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: 

          _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!




   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

      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

   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

   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]

      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

      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

To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org

Reply to: