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

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

> 		-- 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 ?

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: