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

Re: directory structure - 2.

On Thu, Apr 16, 1998 at 12:56:07PM +0200, Christian Schwarz wrote:
> 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 now time to answer the mail in more detail. I haven't finished my
starter, though. Maybe later today.
> 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.

I'll look into all suggestions on this list, and will put some of my own
ideas in it, too ;) I hope this will be something we all can agree on (and I
will try to explain the structure).
> 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.

I agree. I'm not up-to-date with the current situation how doc-base and dww
and dhelp will fit together nicely (maybe I'll play catch up), but this has
indeed nothing to do with the ordering of the documents.
>  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.

Yes. It should be a part of doc-base. As I said above, I don't know what
tasks the different parts have or will get. I consider doc-base as the
back-end and dwww and dhelp as the front-end. Please correct me if I'm wrong.

>  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. 

Theoretically, documents can be stored wherever sections are. But the more
general the section is, the lesser documents fit in (bad english? I don't
care --- mostly german readers here ;)

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

YES! I've ideas, but don't want to start the discussions yet.
>  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.

I think the front-end should display whatever the back-end tells it to do.
>  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.

I'll take a look in my doc hierarchie. It is important to know what
documents exist, so one can take this into consideration.
>  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 ;-)

We could have little flags for the (english version, german version) thing.
So you could see what languages are installed.

Thank you for our proposal,

"Rhubarb is no Egyptian god."        Debian GNU/Linux        finger brinkmd@ 
Marcus Brinkmann                   http://www.debian.org    master.debian.org
Marcus.Brinkmann@ruhr-uni-bochum.de                        for public  PGP Key
http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/       PGP Key ID 36E7CD09

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

Reply to: