Fundamentals

[Paul W. Frields]

Hi, umm, D at 7@k|N&. (Perhaps you should consider using a real name, I
feel really silly typing that!) :-)  I'll break out answers below that
will hopefully be a little helpful for you. Oh, in the future, could you
be so kind as to *not* use HTML in your posts to the list? Case in
point, your post comes out on my screen so small I can barely read it.
It's considered a "best practice" to use plain text only for e-mail to
the list. Sorry for the etiquette detour there, and I apologize to all
if Evolution mangles this reply into HTML.

On Tue, 2004-08-24 at 20:36, D at 7@k|N& wrote:
> OK….so I have a few questions, that (I know) have probably been
> answered a thousand times, and the poor posters were flamed
> continuously for days on end (OK….maybe I’m a member of too many
> mailing lists ;).  Anyhow, I’m curious how you guys work on
> documentation projects individually.  Do you write in your favorite
> text editor, then pass the subject matter to your editor to parse it
> into XML?

You can do this if XML is beyond your means. But frankly, if you're
comfortable writing HTML or using "styles" in your favorite word
processor, Docbook XML is really not any harder. You have to write the
tags, true, but there are tools to help. Read on for more....

>   Are all of you so good that you compose in XML?

I'm a perfect case study for this question. I didn't know *any* DocBook
before last year, and I don't know a ton of it now, for that matter. But
I know *enough*, and it only took an hour or two to get the hang of it.

>   Is there an emacs plugin that I’m missing that allows you to write
> your content, then adds all of the *basic* XML tags for you?

Yes. At a minimum, install psgml, which came with your Fedora
distribution. You should already have installed the "Authoring and
Publishing" group of tools from your System Settings => Add/Remove
Software tool, which is actually system-config-packages.

There are other, and many would argue better, tools, such as psgmlx or
nxml-mode, which are essentially plugins for Emacs. (Emacs devotees,
please don't flame the wording, I'm purposefully simplifying here, in
large part for myself too.) They do all the cool work like highlighting
your tags, indenting things nicely, and letting you use keyboard
shortcuts and auto-completion for tag names.

For example, in psgml, you can hit Ctrl+C, "<" to start a tag, then type
the first few letters and hit Tab to complete the name, or get a list.
Then you hit Enter to insert the tag, and just keep typing. You get used
to this VERY fast. I don't even notice doing it anymore. Other tools
work similarly.

You should read the Documentation Guide, available at the FDP home page
at http://fedora.redhat.com/projects/docs/ ... don't skim it, really
READ it, and you'll learn a lot. I did. Erm, eventually. :-)

>   Where does the author start and the editor begin?

Reading the archives and Karsten's process document (see
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993) will give
you a better idea how this works.

> Do you compose in your favorite editor, then once the content is
> complete, open it in emacs using the template, and parse it that way? 
> What’s the /theoretical/ process, and the /practical/ application of
> that process?  

I just write in Emacs, it's actually easier that way. You can just write
big sections with notes and fill them in later as you go.

> I’ve skimmed the Documentation Guide, and the Quick Start, and didn’t
> get a whole lot out of it other than I should be either an author, or
> an editor.

See above comment. :-) We really need authors right now, to be honest.
It would really suck for everyone to want to be an editor, and have
nothing to edit! You can do both for different documents, but in all
honesty, I would recommend to any new person coming in that authoring is
the way to go right now. Just my $0.02. I have a feeling we will all be
doubling up a bit to get things off the ground in the next few months,
if we don't want to be embarrassed one day by the fact that FC4 is on
the way without (yet again) an installation guide, for example.

>   Karsten has volunteered to be my editor for this particular project,
> so I guess that makes me the author.  ;)  So are there considerations
> to be made while I’m writing the content?  Will those come after the
> fact?  Are they my responsibility or the editors?

His process document will tell you a lot about this.

> I apologize for so many questions, but this is my first “official”
> documentation project, so I want to make sure I get it right.  ;)

Asking questions is always the right way to start. 

> <== dataking's pgp ==>
> 9287 3334 03E4 965E 0D2D  F7CA A6E7 407C 1558 A263

Shouldn't I know your name before I trust your key? :-)  Tee hee, just a
thought. Welcome aboard and hope you're excited about the work, there's
a lot to go around, it seems!

-- 
Paul W. Frields, RHCE