[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Debdoc



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



Reply to: