fedora-list guidelines

[Karsten Wade]

On Thu, 2005-03-31 at 22:27 -0600, Gustavo Seabra wrote:
>  I believe that there should
> be only one version of it.

I agree.  You only want to maintain one source and derive all others
from that.

> The question now comes to which form to adopt: DocBook or Wiki? 
> 
> Based on maturity, since this document has gone through 4 draft
> versions, all discussed openly in the list, I believe it is mature
> enough to get the DocBook format. It would also give it a more
> "official" look. However, it seems to me, the DocBook is a more closed
> format, with more restrict access.

What I understand you to mean is, it is harder to learn how to use and
manipulate DocBook than a Wiki.  That is true.

Otherwise, DocBook is the de facto standard open format for writing
technical documentation.

> On the other hand, being a community born document, maybe the Wiki is
> more appropriate, by giving it a more open character. On the weak
> side, the Wiki would have less of an "official" impact.

My guess is that this document will not need that many revisions.  It is
based on solid principles and tailored to a particular audience.  A Wiki
is a great collaborative tool and gives you quick and easy ways to post
information.  But DocBook is on a different level.

For example:

* DocBook is a single source that gives you multiple output formats --
HTML, PDF, RTF, TXT, etc.

* You can translate the strings in DocBook (the content between the
tags) without having to touch the formatting.  Fedora translators are
used to working with DocBook.

* XML and XSL allow us to add stylesheets for other accessibility needs,
such as producing a high-contrast, large-font output for visually
impaired, or output for text-to-speech programs to use.

My thinking is that if a document is out of draft/beta stage and doesn't
need more collaboration, we should put it into DocBook.

- 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: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050401/19e3d342/attachment.bin