Fedora Installation Guide writer opening

[Robert F. Chapman]

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.

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.


Questions:

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

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?

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.


Thanks,

Robert Chapman

[Chida]

On 7/22/06, Robert F. Chapman <robert_chapman(a)maximhq.com&gt; 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.
>
>  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.
>
>
>  Questions:
>
>  Is the Installation Guide being re-written or just updated/improved for
>  FC6.
>
>  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?
>
>  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. 

Hello Robert,

I feel at home with vi for docbook and wouldn't mind a better tool to edit
documents. Currently  I use vi to edit docbook documents and use the docbook
utils to convert them to the necessary formats. Using vi and rendering with
docbook-tools is laborious and time consuming.

I'm curious about the development environment of other writers as well and
wonder if there are any better tools/methods for document generation.

Chida

[Paul W. Frields]

On Sat, 2006-07-22 at 10:15 +0530, Chidananda Jayakeerti wrote:
>  I feel at home with vi for docbook and wouldn't mind a better
> tool to
>  edit documents. Currently  I use vi to edit docbook documents and use
>  the docbook utils to convert them to the necessary formats. Using vi
>  and rendering with docbook-tools is laborious and time consuming. 
>  
>  I'm curious about the development environment of other writers as well
>  and wonder if there are any better tools/methods for document
>  generation. 
Most of the senior editors around here use Emacs and psgml.  We have a
complete toolchain for rendering documents into HTML so you can check
output in your favorite Web browser.  We can take original composition
in other forms, but since the canonical IG is already in DocBook in our
CVS, it really makes more sense to work on it there.

If we have a team willing to work in DocBook and in CVS, and they do the
necessary work to get a CVS account (CLA, etc.), I will be happy to
sponsor them and we can simply restrict access to the installation-guide
module for now.

As an aside, plain text messages to the list are appreciated since HTML
throws a lot of Linux email clients for a loop.

-- 
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

[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

[Paul W. Frields]

So if we have people interested in helping with the IG, I can sponsor
you for "limited" CVS access -- limited to the IG module for now -- and
oversee any work.  Some of the work we need done right away includes:

* Screenshots for FC6t2 install process.  Use Rawhide for now since it's
"next to frozen," and follow the guidelines given in Section 2.4 of the
current Documentation Guide[1].  Pay particular attention to only
updating the ones that require it -- i.e. a change in the process, a new
screen, or one which says "6" or "6 test2" instead of "5".

* If there's a significant change in any part of the installation
process, try and write some notes about it.  If you want to draft on the
Wiki, that's fine; I and any other interested editor can copy and tag
whatever we can't convert properly.

I am going to Xen-ify a box today so I can start doing some VNC installs
to get an idea of how much things are changing; I'd recommend that as a
first step for interested parties.  If you don't know how to do that,
search the wiki for Xen and/or stop by #fedora-docs for hints and tips.
Docs, ho![2]

[1]
http://fedora.redhat.com/docs/documentation-guide/s1-screenshots.html
[2] Rallying cry, not urbanspeak.

-- 
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

[Dimitris Glezos]

O/H Paul W. Frields έγραψε:
>  So if we have people interested in helping with the IG, I can
> sponsor
>  you for "limited" CVS access -- limited to the IG module for now -- and
>  oversee any work. 
Oh yeah, and since we recently spoke about "good" URLs, we should 
consider changing the URL of the published installation guide.

Current URL:

   http://fedora.redhat.com/docs/fedora-install-guide-en/fc5/

Better:

   /docs/installation-guide/fc5/
   /docs/installation-guide/fc5/en_US/
   /docs/installation-guide/fc5/fedora-install-guide-en_US.tar.gz

-dim




-- 
Dimitris Glezos
Jabber ID: glezos(a)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]

On Fri, 2006-07-21 at 12:52 -0700, Robert F. Chapman wrote:

>  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. 
I'm with Paul and use Emacs + PSGML.  It is obnoxiously good at DocBook,
IMHO.  The block markup (paragraphs, lists) is simple to use, and you
learn the inline as you go.

There is, as always, a small hurdle in starting Emacs and/or DocBook,
but it is much smaller than you realize unless you've never heard of
structured text and markup languages.  But if you do HTML in any editor,
you can be doing XML DocBook in Emacs within the hour.  I know, because
that is how I got stared. :)

Our guide currently covers nxml and Emacs:

http://fedora.redhat.com/docs/documentation-guide/ch-emacs-nxml.html

I haven't tried nXML in a while, but it works similarly; it is a mode
for the editor that gives extended, specific help around the type of XML
document you are writing.  That type is set, btw, in the header:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" ... >

There are some notes in our guide about Vim and XML/DocBook:

http://fedora.redhat.com/docs/documentation-guide/ch-vim.html

YMMV, and maybe there are better techniques now.  If you find them, let
us know so we can update the guide[1]

[1] Add notes to the draft wiki space:
http://fedoraproject.org/wiki/Docs/Drafts/DocumentationGuide

>  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. 
For efficiency sake, I think we should run with what Paul Frields is
suggesting, come to #fedora-docs on irc.freenode.net and we'll see how
far we can get you.  Even VNC is cheaper than gas. :)

That said, I am local-ish to the Bay Area; maybe we could tag a meeting
of Fedorans on top of an SVLUG meeting sometime?  I actually don't
attend, but I've been looking for an excuse to be more ambassadorial for
Fedora. :)

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\