Docs packaging

[Karsten Wade]

On Wed, 2005-08-24 at 01:03 +0200, Peter Boy wrote:
> Am Dienstag, den 23.08.2005, 17:56 -0400 schrieb Paul W. Frields:
> > * Since docs are not absolutely necessary to run a system, Extras seems
> > like the right place to me.  
> 
> Hm, if there is a lack of documentation you can't use a lot of systems.
> Obviously many people can use Fedora despite of a current lack of
> documentation (as we see from FC1 to FC4  :-) ), nevertheless I would
> vote to have the documentation in the core package (at least in the long
> run).

Viscerally, I agree.  However, size is a problem we have to deal with,
and end-user docs with lots of screenshots are big.  And we do hope to
have translations of most of the important ones, so then everyone wants
those included.

For the record, application documentation that comes in the package and
usually ends up in /usr/share/doc/ is not part of this discussion.  We
don't own or affect that content, at least, not directly.

> Perhaps it is possibly to differ between several documents.
> 
> - User guide (if we would have it), yum guide, release notes, etc. 
>   part of core

I could see rallying for this, if the package was small.  The relnotes
exist, and have grown with a screenshot and more text recently, and a
general Fedora Desktop User Guide that had many good bits within would
be quite useful.

Unfortunately, those who need such docs are usually the ones who need
more screenshots than CLI usage, and thus the size of the docs grows
hugely.

> - program related guides bundled with the program (e.g. Samba 
>   guide in the Samba devision), either in core of extra, depends
>   on the programs location

We would have a harder time arguing for Samba docs to be available in
Core just because Samba was.  I think these are perfect for Extras.

> - guides about broader, but special themes in extras (e.g. 
>   rpm packaging guide)

Yes, et al.

> >   Nor should we really bother -- Extras is
> > not a second-class citizen or a myth, 
> 
> It isn't indeed. But may be you need some kind of documentation before
> you can use it (e.g. yum guide) or even know about it.

Aside from inclusion in Anaconda, there is definitely value in a Desktop
User Guide.  Maybe it has few screenshots and is just a master guide
that sends you to more online documentation, call it a Desktop Quick
Start Guide.  One thing it does is get you into using yum/pup.

> > * 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)
> 
> Very good idea in my opinion!

Note that this content, owned by the fedora-release package, is actually
drawn from the release notes that we write.  So, we are in direct
control of this content.

Now, getting stuff about the Table of Contents is XSL-fu work that we
need to consider.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
-------------- 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/6396e941/attachment.sig>