Re: Intent to create: QtEZ

["Pavel M. Penev" <kal_pav@sz.techno-link.com>]

On Fri, 14 Jul 2000, erik wrote:

>    * Unimportant comment: This process, along with much of the debian
> documentation is fairly difficult to digest and quite time consuming. I
> have been using, installing and administering debian full time for almost a
> year ( which I am sure brings me almost up to the level of Rank Beginner )
> and I still have a hard time getting through the docs and beuracracy - is
> there any interest in working on simplification or refining ( ie. making
> more accessable ) the documentation et.al. ?  It really is a great platform
> and I wish more people could use it with less hair pulling... B=).

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 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).

	3. How is the package used. (-- this is the tough 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)
		-- Documents explaining the usage of ALL the capabilities.

	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.)



General rules a consider useful:

	1. Use explicit expressions, e. g. make it possible to understand
what does a paragraph explain even if it is on it's own (wihtout the
surrounding documentation). This rule may not be useful for the tutorial,
and should be really useful for indexes.

	2. Use structured paragraphs, e. g. make the paragraph's first
sentence tell what will the paragraph explain in detail.

	3. Divide the documentation is as deep as possible hierarchy (note
this just on the contrary of as wide as possible).


My comments,
Pavel