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 [EMAIL PROTECTED] for public PGP Key http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/ PGP Key ID 36E7CD09 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
