what next?

Karsten Wade kwade at redhat.com
Tue Nov 7 13:51:29 UTC 2006


On Mon, 2006-11-06 at 17:17 +0000, Dimitris Glezos wrote:

> I believe we should try to organize our docs in a way that they could be 
> combined into one document (Fedora Handbook?). We have talked about this 
> in the past: this should be developed in a modular way so that each 
> document (chapter) has an editor and some writers. See a recent 
> discussion at [1], [2]:
> 
>    [1]: http://www.fedoraforum.org/forum/showthread.php?t=125807
>    [2]: 
> https://www.redhat.com/archives/fedora-docs-list/2006-October/msg00081.html

+1

That has been the goal for about ... 18 months?  Looking at your
outline, we have a large amount of that work done already -
installation, desktop usage, release notes, FAQ.  

I've hesitated at taking on a large project for a single document output
that requires so many people to make it happen.  For the first time in
this project's history, I think we can do it.  It means many of you are
going to need to learn to write in a consistent style using a common
voice and common markup.  But the momentum is here as well as the need,
and obviously we are desiring a single, unified Fedora Handbook. :)

There are still tools we need in place to make this work right (Plone,
PDF toolchain, Wiki <-> XML), but these are just implementation details.

> The goal should be to ship a new guide with each release that will be 
> available in PDF [3]. If we succeed in this, then we will have a 
> printable manual for Fedora -- something very important IMHO for any 
> person's bookshelf.

http://fedoraproject.org/wiki/DocsProject/Handbook

Let's work out the structure and other process details/tasks there.

>    [3]: http://fedoraproject.org/wiki/DocsProject/Tools/PDFconversion
> 
> Having such a goal will give us a vision much greater than "just a doc 
> on a subpage of our website". I believe that it's importance will be 
> greater than the sum of the current's docs importance; for example, it 
> could become something that the FreeMedia program could ship for free 
> too, or ambassadors hand it (or parts of it) at events and we will have 
> to have it ready by the release date.

+1

> One easy way to handle this would be the wiki, like the Beats with a 
> clear hierarchy that has cross-references between chapters. This way, we 
> could monitor the changes and docs members could "maintain" chapters. If 
> we go with the wiki-way, we can have people chip in here and there more 
> easily.

Yes and no.  Until we have a entirely Wiki front-end to DocBook, there
is some content that we are going to have to work on outside of the
Wiki.  The Installation Guide comes to mind here; converting it to the
Wiki losses much of the semantic markup, and since we'll have to convert
it back out eventually, I don't think it is worth the effort for the
small amount of additional contributions we'd get via the Wiki.

What we could look at doing is a "scratch" conversion, that is, make a
Wiki version of some of the XML content, then do a semi-manual
conversion of the content back into the XML in CVS.

Other content we may choose to have live on the Wiki as the source
content.

> Some sample contents:

I moved all this to the DocsProject/Handbook page to collaborate on it.

:) - Karsten

>    * Introduction
>      - The Fedora Project
>        + What is Fedora, FOSS, History
>        + Getting help, Communicating, Participating
>      - Packages
>      - Glossary (jargon-buster)
>    * Fedora Core 7: Tour, Release notes
>    * Installing Fedora Core
>    * Using Fedora's desktop
>    * System administration
>    * Tips and tricks
>    * FAQ
> 
> And here are some more references:
> 
>    * TLDP guides [4]
>    * Old "Linux Manuals and Documentation" page [5]
>    * Gentoo Linux x86 Handbook [6]
>    * Debian GNU/Linux Desktop Survival Guide [7]
> 
>    [4]: http://tldp.org/guides.html
>    [5]: http://www.estart.co.za/linux_doc.html
>    [6]: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1
>    [7]: http://www.togaware.com/linux/survivor/
> 
> 
> My 2 cents.
> 
> -d
> 
> 
> -- 
> Dimitris Glezos
> Jabber ID: glezos at jabber.org, PGP: 0xA5A04C3B
> http://dimitris.glezos.com/
> 
> "He who gives up functionality for ease of use
> loses both and deserves neither." (Anonymous)
> --
> 
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- 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/20061107/4131bf22/attachment.sig>


More information about the fedora-docs-list mailing list