policy propos [was: Re: doc-section madness]
Hi,
Just I stated I don't feel to be the right person for
proposing a so important policy (registering of doc-base). My problems
are: no good english lang, no great experience with problem like
admin, no debian longtime user (1.5 years now), not a debian
developer.
iirc, Wichert Akkerman plans to add features like user template on his
doc-central. This feature will make easy for an user to decide what
kind of document he is intered on and how they have to be organized.
My point of view could be more low level: any user have to split itself
in end-user, developer and system administator depending on what he's
searching for.
The problem of a good organitation of doc-base system is unlike for
user, who can be disoriented, and for debian maintainer, who'll have
doubt on policy to adopt. While a developer is an user too, defitely i
think there's a gain for the whole word if debian will adopt a policy
for documentation (or better, a leading line).
To decide a policy on documentation is an hard (arguable) work, so
please comment extensively on where I'm wrong, what I miss, what a
package specific issue, and so.
_Leading Lines on register doc-base_
Those want to be only an help for debian maintainer for the choice of
section where register documentation when there is a choice. There are
no "must" here, this policy intent to make easy the work of packaging,
also serving the users needs for productivities.
First it has to be known what an "user" needs.
Here "user" is used (argh) as a end-user, developer, system
administrator and in general anyone use debian system.
Again, divide exactly what are the end-user needs and the developer
needs is a matter of taste : i.e. latex documentation is for end-user
or developer one ? and the same for sgml, html, emacs-lisp, ..
So I propose to divide user between "Desktop user" (yes ala windows:
the time is up for debian too) , "Developer", "Debian developer",
"Admin".
Desktop-user need to be documented on how to use a program or application,
so the existing "Apps" section is ok. Another section for end user
could be "Help" where an user can find think like lg or other thing
like tips & trick. Now "Apps" section contain a subsection named
programming: it will be wrong.
A special section "Debian" (just to know you are really here) will
contains a subsection called "Help" (for end user) and another called
devel (where to put policy manual, developper reference, debian policy
and all development things strictly related with debian system)
- Section "Devel" will contains subsection for System, Electronics,
Tools, Terminal, Graphics, Math, Net, Text (processing), TeX,
Extention-language. CONTENTS: referense strictly need from developers.
"System" is for kernel driver interface, filesystem and so.
"Electronics" is for circuit programming libraries interfaces and
such.
"Tools" contains docs on programming/hacking tool, documentation tools
(like doc++) and compiler/interpreter reference.
"Terminal" is for curse programming, dialog and all text (terminal)
based interface libraries.
"Graphics" is for graphics programming reference: fb, svgalib, and
XFree server based library (and Xfree itself) like tk, gtk, lesstiff,
imlib and such.
"Math" for math library (not applications extention languages)
"Net" is for specific language an library oriented to networking.
"Text" is for tools like jade, sp, tidy, html-reference.
"Extention-language" is for extention language of application, if
user documentation is splitted in main stream package (like elisp
reference).
When a project become a stand alone section has to be
coordinated with maintainers of other packages that should go inside
the new section. i.e. gnome, kde are projects for made an easy to use
desktop environment but include things like network interface,
configuration file management and so: it should be a gnome and kde
subsections inside "Devel" (same policy applied to TeX). Zope is
another "it could stand alone" subsection ..(add other here)
- Section "Apps" will contains subsections for any major project (I want
to know something about gnome or kde not something about graphics) and
apps like gimp will go in "Graphics" section, Math tool like drgenius
in "Math" section, other sections could be: "Editors", "Sound",
"Electronics", "Net", "Web", "Viewer" (preferible to merge with
graphics), Terminal (for things like mc, and so)
- Section "Admin" will contains documentation on configuring a server,
but a desktop enviroment too: smtp agent, web server, ftp server,
service, network configuration; but also emacs site management, TeX
site management and for documentation on device driver
configuration. I've not idea on how to organize that section in
subsection, I think that no subsection could be ok here, but I see
natural to divide in "Networking", "App-Config" and "System-Config".
FUTURE TODO: add a frequently appeared issue with example of existing
packages and the policy choices.
I don't know if it is good but at least there is an idea now to
discuss on.
Still not subscribed to the list (for this night) soon there
Daniele.
--
Daniele Cruciani <cruciani@cli.di.unipi.it>
Universita` di Pisa - Informatica -
http://www.cli.di.unipi.it/~cruciani/
Reply to: