Docs packaging

[Paul W. Frields]

I want to take a stab at packaging at least a few of the biggie Fedora
docs for FC5.  Some of these thoughts below:

* Since docs are not absolutely necessary to run a system, Extras seems
like the right place to me.  Putting Fedora on a diet was discussed
endlessly before and after FC4, so I'm not sure we can make a great case
for getting docs into Core.  Nor should we really bother -- Extras is
not a second-class citizen or a myth, it's a living, breathing, vital
repository where we can be proud to have our documentation.  Plus,
putting it in Extras means it can stay fresh, which is absolutely
important to this project.  (I have Extras membership, as do some of our
other contributors, and can easily find someone to review the package
for inclusion.  In fact, any of you could do it, and probably should, to
speed the process up.)

* Packages will consist of HTML.  The XML will be in the .src.rpm as
expected.  Building to be done via the buildsys/plague per normal
routine, unless someone has a better idea that doesn't require a lot of
manual intervention.  We don't really need our own buildsys, since the
docs packages would live in Extras anyway.

* As far as the process goes, I see it as snapshotting the CVS for
SOURCES stuff, updating Extras CVS with the results, and do a build
request on normal channels.  Package versioning is done from the CVS
date, per Fedora Extras guidelines.  The resulting packages can be
linked from the f.r.c/docs/* pages alongside any tarballs.

* I am not keen on a single docs package, because updates should be
available on a rolling schedule in very small pieces.  Some documents
require large files bundled in the package; an example is the
Installation Guide, which has a few MB worth of screen shots.  Users
should not be required to download that amount of material just to get a
new release of foo-tutorial.  A better organization would be:

  * fedora-docs-common: Anything used by all the docs, such as CSS;
probably to be installed in %{_docdir}/fedora-docs/
  * fedora-install-guide: self-explanatory, sits in
%{_docdir}/fedora-docs/install-guide/
  * fedora-documentation-guide: ...and so forth...

Note that these are not subpackages, so that their version information
can move independently and track the revision history in each doc if
need be.  This is especially important with the canonical guides,
although I could see using CVS dating (i.e. M.m-R.YYYYMMDDcvs) as well.
My preference would be to keep it simple if possible.

* I would like the /usr/share/doc/HTML/index.html file (which is part of
fedora-release, and comes up when people launch Firefox) to show a SHORT
and informative menu on how to:

  * Read the release notes
  * Install and update software, in particular Fedora docs
    (i.e. "yum install fedora-docs\*" plus link to Stuart's yum doc)
  * Access fedoraproject.org, especially the Wiki
  * Get involved in Fedora (probably also through fp.org)

This menu should simply be incorporated at the top of the release notes
to minimize clicking around for new users as well as the work required
to get it in under deadline.


I'm sure everyone can come up with additional thoughts -- I am trying to
jot all this down quickly, so I've likely forgotten important things.
Have at it, please!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050823/389bf061/attachment.sig>