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
