On Sun, 23 Jul 2000, erik wrote:
> 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. Actually as far I see docbook provider its own Document Type Definition (i.e. it has its basic tags defined). I have also downloaded the XLM documentation from "http://www.w3.org/"; and intend to read them. > 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. I think that with a good browser, the users would even not notice the document is in XML insted of HTML. (Howerver, I think this brings another issue -- there not many XML browsers nowadays, and what about porting to another OS?). > 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? Unfortunately I havent found a tool like "man2docbook"; however docbook is a standard, so we can request from all the Debian maintainers to provide valid docbook documentation. > 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. Hope we achieve this (or isn't this why people call some developers?), Pavel
