fedora-list guidelines
Karsten Wade
kwade at redhat.com
Fri Apr 1 08:17:41 UTC 2005
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: 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/20050401/19e3d342/attachment.sig>
More information about the fedora-docs-list
mailing list