Fedora Installation Guide writer opening

[Paul W. Frields]

On Fri, 2006-07-21 at 12:52 -0700, Robert F. Chapman wrote:
> I wouldn't mind getting involved with the Installation guide. I really
> think I need some guidance and mentoring to get started.  I have looked
> at many of the guides but still haven't found a starting place.
> 
> I'm very new to the Doc-Book style and methods. I have yet to to find a
> tool to help me with creating Doc-Book documents, by hand is fine as
> well (vi is my close friend).  I am currently working on a couple of
> documents for my work, I am trying BlueFish as an editor, as it seems to
> handle many of the tags for doc-book.

Last I checked, unfortunately, BlueFish didn't do validation... has that
changed?  That's not really a showstopper though.  (Validation, in case
you're not familiar with it, is the process of checking that a document
adheres to the DocBook definition -- in other words, that all the
elements are legal, properly nested, etc.)

> I need to come up with a development environment that allows me to
> easily turn my plain text ruff drafts into well structured documents.
> Examples of others development environments and methods would be most
> helpful to get me started.

The following was my experience in using both Big Kahuna editors; all
further vi vs. Emacs comments to /dev/null, please:

I was a vi guy before I joined FDP, and now I do Emacs almost
exclusively.  Its insane level of DocBook functionality is what tipped
the scales for me.  I struggled to get out of the habit of <Esc>:w and
into the habit of Ctrl-X Ctrl-S, but after I had been working in Emacs
for a week or two it was second nature.  Since it's a validating editor,
if I use the keystrokes for opening and closing elements, Emacs makes
sure I stay legal.  I can't open a "wrong" element, and it always closes
the nesting properly.  If vi has these functions too you would do well
to make use of them.

There are very few other editors that will really do a good job of
dealing with DocBook.  You can try converting to OpenOffice.org and then
saving to DocBook XML, but in general it misses a LOT of the elements
and structure other than simple sections and headings.  And it usually
gets all the nesting wrong.  The Conglomerate XML editor is a nice idea
but frankly, it's just a GUIfication of a text-style editor, and one
that crashes constantly at that.  Plus it doesn't support DocBook XML
V4.4, which is what we use around here now.  Bluefish is pleasant to use
but has very limited functionality -- it colors your tags and that's
about it.  (You can get the same in Emacs and, I would bet, Vim as
well.)

> Questions:
> 
> Is the Installation Guide being re-written or just updated/improved for
> FC6.

If that's a question, where's your question mark?  Oops, that was the
editor in me coming out. ;-D  Seriously though, it's probably not going
to be thoroughly re-written for FC6 since FC6 itself is not a huge
change from FC5.  As the previous second-chair on the Installation Guide
I'll be willing to oversee any team that wants to work on it, but we
need to get started right away.  I don't predict making major changes
this time around.  If we want to do so, nothing prevents us from waiting
until after FC6 release to do the overhaul.

> I have yet to install FC6-test1, and will have to do so. Are
> others/developers providing information for the guide or would I be a
> sole contributor?

You're always part of a team around here.  Refer to other recent email,
case in point.

> Are there any members of the doc-list, located in the S.F. Bay area that
> I would be able to meet with to help get me started? I work in Sunnyvale
> Calif. and love Starbucks. I also frequent a couple of the local Linux
> Users Groups.

Hey man, this is the 21st century! :-D  Just hop on your IRC client on
Freenode at #fedora-docs, where you will find people willing to answer
questions and guide you.  Email is sometimes lousy for that purpose
because of the delay.

What we do *NOT* want is for everybody to be working on things in their
own sandboxes.  That's a recipe for disaster and frustration.  Because
the canonical Installation Guide is in DocBook and in our CVS, we really
need contributors willing to do what's necessary to learn these (pretty
easy, really) technologies.  It sounds like you're one of 'em, so get on
#fedora-docs and let's talk!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
       Fedora Project Board: http://fedoraproject.org/wiki/Board
    Fedora Docs Project:  http://fedoraproject.org/wiki/DocsProject
-------------- 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/20060722/a4456b33/attachment.sig>