On Tue, 25 Jul 2000, Dmitry Borodaenko wrote: > On Sun, Jul 23, 2000 at 07:40:32AM -0700, erik wrote: > > On Sun, 23 Jul 2000, Pavel M. Penev wrote: > > > > > > > > I think we could make the "index" page contain the introduction and make a > > > separate page on installlig, huh? > > ----Dmitry: > "The major conclusion reached by attendees was to standardize on > DocBook/XML as the canonical format for open source documentation. > The role of DocBook, however, is to be the storage and exchange > format. Different projects will use it in different ways, but all > will provide some form of their documents in a standard DocBook > format".
> The package you plan to work on is a Good Thing, and I wish it not be > spoiled by use of HTML. Why HTML, when everyone and his mother uses or > moves to DocBook over SGML at least? Anyone who can write HTML will not > need to learn much before starting to write XML docs. That's a good point. I don't know much about XML but its worth looking into. However, thinking in terms of pages, indexes, and links works well for me as an organizational tool. Also, at least from my perspective, the main point here is to create a tool that produces some templates with some default content that may be [hopefully ;)] easily filled out and installed as companion .debs to <pkgfoo>.deb. The tool should also provide a single point of entry to these companion .debs as well as documentation on itself and perhaps a small searchable database of the "debdoc-<pkgfoo>.deb"s installed. The purpose of this is to provide an accessible UI to the documentation that is already available and additionally a structure in which to effect improvements or add things (eg. short tutorials) that are missing. I think that asking everyone to rewrite their docs for this little notion might be a bit much. But if the structure is there in .deb form it can be: A. Easy to adopt and maintain B. Easy to expand and improve C. Easy to install D. Easy to integrate with existing docs (via links) E. Easy to find >#update-menus and its there F. Optimally self-administering ( one shouldn't have to be a professional sysadmin just to have good docs available ) G. Easy to get rid of if it annoys you :) And if it is in a form similar to a website ( something most people are now somewhat familiar and comfortable with), it will be easy to navigate. Yep, I know; I said easy several times - for this reason: perhaps the most central factor of all new learning is the level of comfort or relaxation present in the learning experience. For many people ( not so very long ago me for instance ... ;)) a text screen with cryptic key commands is simply frightening and strange. Then you are in a catch22 - you need to learn the system to use it to learn the system ... a schizophrenic double bind. Not good for learning. But, given a familiar interface, the same people will burn through ten pages of the same info in short order. Info and man pages are great once you know how to use them but you have to start somewhere and for the non-obsessed using (eg.)a forward-slash to search is a deep scary Secret Knowledge and simply confusing. Hence the HTML - but if XML can give us the same result and still support all browsers then maybe that's a good direction to move in. I only wonder about tools I had in mind to use for simply integrating existing docs ( eg. man2html) - is there a man2xml? I hope that the other ( and equally important ) purpose of providing a skeleton for "structured documentation" will to some extent arise from the creation of the tool itself - and that the form of the tool will in turn be informed by that skeleton at the same time. This may well grow into a full-fledged general documentation system over time but I personally hestitate before thinking _too_ grandly. I have a fat head as it is and they just don't make pillows any bigger ... For me it would be enough if my mom could fire up the debian machine I'm going to make for her and be able to learn how to do something with it ;-}. I think I may be ranting ... must sleep now. Regards, erik
