Re: Debdoc

[erik <devvnull@crosswinds.net>]

On Wed, 26 Jul 2000, Dmitry Borodaenko wrote:

> > 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. 
> 
> Maybe I've lost your track here. Are you going to help people
> write/improve docs, and integrate such advanced docs together? Or are
> you going to take all existing docs, and transform/reorganize it with
> your tool?

 For me that's an important part of the goal - Simply that a novice could
even _find_ docs  would be a big improvment. And once she finds them they
should be easy to navigate and understand.
 
> OK, I see that you have two separate tasks: consolidate together
> existing documentation, and provide a framework for documentation
> improvement. 

Exactly. And this does not mean in many cases doing anything to the
existing  docs - I really do _not_ want to create more obsure quasi
mandatory guidelines and regulations to bog down maintainers. If people
want to adopt the framework or gradually migrate to it that's fine - and I
hope that the framework will make it simple to do that. But initially I
think that links to "Other Documentation" is enough. For instance Qt has
execellent documentation  and a gook tutorial in HTML that ships with the
library: in their case is would be easy to just put a link to this in a
prominent place. I had the libs on my machine for quite awhile before I
even knew the tutorial was there! 

>     www.debian.org/~aph/debian-metadata.html/
> 
> Is it close to your work? Do you think you should coordinate your
> efforts? I think yes, or else you will duplicate.

I hate to say this but this page was a good example of exactly the sort of
inaccessablility that bugs me: They start right off with a bunch of obscure
and previously undefined terminolgies and, after a cursory definition,
begin constructing complex rulesets with them - which are of course to be
followed on penalty of derision ... I don't want to make this complex and
obscure personally, _My_ interest is in elegance and accesability. There
are many intelligent people that would love to help in free software that
are kept out by this kind of difficult obscurity in rules and terms. I
think people do well when things are enjoyable and, although I enjoy an
elegant complexity, this sort of impenetrability is another story. 

 I honestly cannot tell you if we are duplicating their effort - and I
frankly do not have several hours to spend deciphering their
terminolgy and intent at the moment. But when I do I'll try to look at it
again. so thanks for the tip. 
However, it looks to me like they are saying everyone should rewrite
their docs to fit the new format - I think it will be great if people make
use of the templates we are thinking about but they  don't _have_ to -
debdoc will still work to help people to find what's there. Additionally,
I believe we are proposing a _style_ of composition in the ddoc templates
which is something I didn't see over there - but I might have missed that. 

> There are all possible kinds of XML parsers, filters, and perl modules
> all around. You can at least use DocBook stylesheets to convert XML 
>documentation into HTML site, and read it from any browser. 

That sounds cool. I think Pascal is looking at it now - and I will as soon
as I can.

Thanks for the thoughts,
erik