Rough start...

[Karsten Wade]

On Sun, 2004-08-29 at 07:59, 'D at 7@k|N&' wrote:

You are a perfect candidate for PSMLX:

http://dulug.duke.edu/~mark/psgmlx/

It's designed to help newbies to Emacs _and_ DocBook.  Mark is working
on a short tutorial around PSGMLX, so you can wait for that if you want,
but installing and trying it out is easy.

Helpful points:

* More colors to help you out.
* Automatically parses the DTD when you load the XML file.
* Right-click will show you menus of tags that are available at that
exact location.

Then you can use all of the PSGML keybindings you don't know yet, but
will learn to love.

> On Sun, 2004-08-29 at 21:30, Paul W. Frields wrote:
> > On Sun, 2004-08-29 at 08:16, D at 7@k|N& wrote:

> Unfortunately, I'm not that organized, so I don't know when I will
> actually have time to work on this.  So, an actual timeline might be
> tough.  This weekend has been a great opportunity to get familiar with
> the tools, and start getting some content together.  

A strawman milestone schedule will work, but don't feel that is
required.  You could also attach your XML in various (broken) stages, or
other updates and questions.  For questions, make sure the proper people
are on the cc: (such as an assigned editor, who you don't have yet).

> Well, that was the thing.  The XML in general was killing me, and I
> wanted to get some basic content put together.  SO I just wrote out the
> content in kate, and then went back and added the XML tags, modeled
> after the doc-guide.

I sometimes write in plain text and then add tags.  That's a very
legitimate way to work.

> > The only reason to have separate documents is if you are doing a truly
> > long work, and the amount of content requires it. (It means chapters can
> > be assigned separately, for instance.) The Installation Guide's a
> > no-brainer for that; so is the Doc Guide. 
> 
> So, this should more or less be one monolithic document.

It can be, but if you want to break out your sections into separate
files because they are getting long, you can do this with any section
you want separate:

1. Define this at the top of your main (parent) XML file:

<!ENTITY SECTION-FOO SYSTEM "section-foo-en.xml">

Then where you want the section(s) to appear, you put:

&SECTION-FOO;

Of course, you need to respect the nesting rules and call those sections
only where they are allowed.

> Verbosity, and scope of content was never an issue for me.  I used to
> handwrite write 1500 word, open book, essays in an hour (in class) when
> I was in high school ( a loooong time ago ;).  I think that a document
> of the magnitude you describe would be no problem for one person if the
> content is driving the document.

To quickly revisit the reasoning I still support tutorials over long
guides:

My job at Red Hat is to write and maintain two guides of about 100 pages
each (when printed to HTML).  They'll likely grow in time.  But that is
the core of my entire job.  40+ hours per week, every week, every month,
all year, to keep track the technology as it progresses, how it
interacts with our solutions, and write about them. 

Unless your employer is going to pay you to spend about 1/2 of your time
on writing and maintaining a Fedora Security Guide, I think you're going
to find it's much more time than you are willing or able to volunteer. 
Remember, writing is much more than just flowing words onto paper. :)

Now, for larger guides, I really like the idea of the modular approach. 
It's like other parts of open source development, giving us all
something that is within our available time to write and maintain, which
comes together in the end to make something synergistic.

> > Our current (and very pressing) need for an Installation Guide seems to
> > say to me that you may want to participate on that as your "initial"
> > project, and then move on to this once you've cut your teeth there.
> 
> How do I do that?  How do I know what needs to be done, so that I'm not
> duplicating work?

Good question. :)  We need to work on that early this week, deciding
which sections to have in the ToC, and then assigning them.

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41