Re: Debdoc
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
Reply to: