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.
Yes!
> 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.
Yes.
> 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,
Marcus
--
"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: