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

To doc or not to doc, that's the question. (long RFC)

Hi folks!

Although unrelated, the recent thread about the ftp site organization
has made me think (happens :-) and at last one idea came. But let's
start from the beginning.

The problem.

* We have too many docs.
  These docs will fatally grow, as we will set policy for formats to
  supply and as we will organize the translations in other languages.
  We can safely expect a package large as the linux HOWTOs be
  multiplyed in a matrix of n formats by m languages.
  I can give you an example: an italian publisher, wanting to jump on
  the linux market, without investing too much in a full original book,
  is publishing a book with the whole Linux Howtos translated into
  italian. Our translation team was slowly doing the job, when they
  stepped in and _payed_ (other people) for the missing translations.
  So now we have simply to keep all up-to date; expect a 2 mega package
  with italian howtos in different formats.
  {text,html,sgml,ps} (one could say: why not acrobat?)
  I don't think we should wait too much to see the same happen in
  Germany or in France, and a book with the manpages, etc.
  Consider also that the "source" package for these docs is simply a
  duplication of the binary package.[2]

* Most of these docs are chronically out of date.
  Actually we keep all those packages INSIDE the distribution.
  Though, even if the maintainer does his best to release an upgrade
  every month, the package goes frozen and later released and burnt
  into CDs. So our users have CDs with tons of docs that are old two
  months in the best case, and even 8 (have you noticed that we are
  releasing every six months?). Our users are discuraged to install
  things from unstable, and they can't know if some hidden dependency
  doesn't oblidge them to install a whole bunch of packages, if they
  decide to install the latest RFC ...

* Maybe hamm will, but probably the subsequent will not fit in two CDs.
  I don't have any number, but I think someone else could fill this

The solution.
(one of the many, almost)

The idea is to move the "doc" section up in the hierarchy of the FTP
site, promoting it.
Actually we use a four level scheme in the FTP organization (naming is

¤ the "distribution" level, in which we separate stable from unstable,
  Debian-1.3.1 from development.

¤ the "support" level that we added from hamm, in which we separate
  arguing on the freedomness of the packages: main, contrib, non-free
  and (as suggested) non-us.

¤ the "type" level, in which we separate disks, sources from binaries,
  keeping each architectury separated (not well separated, but we could
  live well with it)

¤ the "section" level, in which we separate packages in base of their

The proposal I'm presenting here is to promote the docs pakages from the
"section" level directly to the "support" level (or even the
"distribution" one), adding "documentation" to contrib, main and
non-free. We could even subdivide it into binary and source, if we want,
but I strongly suggest not to do so[3]. we can anyway subdivide into
sections argumented after their matter, as proposed some time ago and
never decided.

But that's not enough.
Starting from hamm, also contrib and non-free will be frozen, so we need
to set a policy that the docs will not be frozen, and maintainers could
continue to upload there even after the release has happened, provided
that there are some (more or less) automatic checks on the package
integrity and organization and a check on the proper dependencies [4].

What's the benefit?

We can tell the user that is safe to download packages from the doc
hierarchy, if they are running the latest stable.
We could even tell the CD manufacturers to issue regularly upgrades
based on the docs directory (and the stable-updates as weel, thus
separating the distribution from more or less frequent upgrades.

I strongly suggest to issue a monthly third official upgrade CD based
mostly on the upgraded docs, but containing also stable-upgrade.

Thus my proposal:
* promote the docs package in the ftp hierarchy.
* make a less strict policy on their release
* release docs officially separated from the binary distribution.

It was a long read, I know, and maybe not so fun as it could have been
if I were a native english speaker, so thank you for your patience.


[1] As another example I can teel that even if I have stopped a while in
releasing the monthly issue of the Pluto Journal, now in Italy there is
also the translation of the Linux Gazette as a monthly newsletter; such
kind of things are growing, believe me.

[2] In a pure doc package there is no compilation or transformation at
all. For packages not pre-packaged upstream (like the HOWTOs), but
directly downloaded from the Net, the notion of "source" is even more
volatile. Maybe we should imagine a binary package in which the tar.gz
is the source package itself!

[3] I think that most (if not all) of the pure doc packages doesn't have
a source separate from one of the derived binary, or otherways its
source (in case of a doc derived from a big package) is yet included in
the right source directory and doesn't need to be here.

[4] No dependency on packages out of the stable release. We could even
have a temporary doc directory inside unstable to handle packages that
will be relesed only with next release, because of dependencies.

| fpolacco@icenet.fi    fpolacco@debian.org    fpolacco@pluto.linux.it
| Pluto Leader - Debian Developer & Happy Debian 1.3.1 User - vi-holic
| 6F7267F5 fingerprint 57 16 C4 ED C9 86 40 7B 1A 69 A1 66 EC FB D2 5E

TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org . 
Trouble?  e-mail to templin@bucknell.edu .

Reply to: