Re: Intent to create: QtEZ
Hello Pavel,
Thanks very much for the input - maybe we can get something going here.
On Fri, 21 Jul 2000, you wrote:
> I am concerned about this point, too (the "Unimportant
> comment":)). Many packages have tons of documentation. It is often really
> time-consuming to find out what you need. I have thought of creating
> something like an ANSI documentation. I expect a large number of
> objections here. Nevertheless, I think it will be good both for the
> documentation authors and their readers. The problem I see here is to
> define a well balanced set of rules that a documentation should meet.
* I think that one way to achieve this is to have a predefined format
that can simply be filled in with the specifics. This would provide an
opportunity to (for example) new users of a program to learn about it and
help out maintainers by contributing to the documentation. I recall
mention of making it easier for people to pitch in with help at the recent
debian conference in France; seems this might be an appropriate avenue for
that sort of thing.
Ironically the model for this which came to mind first was the KDE
documentation framework - although their docs are not usually very good
(sorry guys, its true ;)) the format really has a good structure. Its a
prebuilt set of HTML pages that go to a consistant place. One of the
things that I find difficult in debian is that /usr/share/doc/<pkg>
frequently only has a debian readme and the copyright info - there may be
tons of docs available but who knows where?
(eg. /usr/lib/<pkg>/doc/libs?/html/en ... and so on.)
The nice thing about a prebuilt set of pages is that it would fit in
nicely with dhelp and/or dwww and could be indexed and searched (SuSE has
a nice setup for this kind of thing). Then each package could have a
consistant <pkg>-doc associated with it (as "Recommends:") that would go in
one place and _automatically_ be added to a central index. It doesn't
matter if it has not been totally filled out - this gives people an
opportunity to contribute without being completely obsessed hackers ;-}.
And hopefully the result is a standard and improving documentation base
for debian, no?
There are plenty of tools to make this easy, for example man2html and
friends. I suppose the best would be a small suite ( hmmm, how about
debdoc ? ) that would:
##############
==>A. build a series of prelinked pages ( see for example the default
docs produced by Kdevelop at project creation )
#############
==>B. Extract some basic package info from .deb control fields and
fill out the first page with this info. _\/ fullfills the items below
> I think every documentation-package should contain information about:
>
> 1. Author(s)/maintainter(s)/etc.
>
> 2. What capabilities does the package offer (a short and a
> detailed description).
#############
==>C. Optionally convert the exististing man page to provide at least a
default for:
> 3. How is the package used. (-- this is the tough one.)
Note: this ^^^^is where work and potentially user input is most likely to
take place. Keeping it in one section might help reduce the chaos ;-/.
#############
==>D. Provide a skeleton for tutorial to be filled in by some one very
clever... or simply install and/or link to a provided tutorial if there is
one.
> -- A short tutorial showing the most-often-used
> capabilities of the package. (it's good to start with something before
> reading a 300-500 pages of documentation)
#############
==>E. ...?? ideas here?
> -- Documents explaining the usage of ALL the capabilities.
#############
==>F. Provide a skeleton for technical info to optionally be filled in by
the author or someone equally knowledgable. Covers the below VVV.
> 4. Technical informaion -- what algorithms does the application
> use, what is the coding style, what is the directory structure of the
> source code (-- the last two may be present only in the source package.)
The basic idea is to build a tool that could easily be applied to any
deb-standard package and leave space to fill out the resulting framework -
I think this might go a long way towards improving the clarity and
accessabilty of documentation as both creating and reading it could be
done within a consistant framework. I realize that there have been
attempts to do this ( man pages, info, etc...) but it does not seem to
have really come together as yet. I also think that many of the functions
can be supplied by existing programs ( dwww, dhelp, info2html etc) -
simply a question of putting the parts together in the right order ...
More Comments ?
Cheers!
erik
PS: I cc'd this to debian-devel , but I wonder if there is a different
list that this should be going to?
Reply to: