Rough start...

[Paul W. Frields]

On Sun, 2004-08-29 at 10:59, '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.  

Once you're more familiar with the tools, like anything else, projecting
how long it takes to get things done gets easier. Sounds like you're on
your way.

[...snip...]
> > 6. When writing a tag, hit Ctrl+C, < to open the tag, type the beginning
> > of the tag, then TAB to autocomplete. I used this feature to discover a
> > lot of other tags, but I try to stick mainly with the ones in the Doc
> > Guide. If I find a situation not covered, I visit:
> >   <http://docbook.org/tdg/en/html/docbook.html>
> > The ToC there has a list of tags with short summaries of what each is
> > for. That's really helpful!
> > 
> > 7. If you have to port in XML written elsewhere (I call that a "last
> > resort," avoidable if you really spend some time with Emacs), make sure
> > you have a DTD section at the top just like the example-tutorial. Parse
> > DTD with Ctrl+C, Ctrl+P, then Ctrl+C Ctrl+Q to resculpt the indentation.
> > This part can get ugly, which is why I prefer to just write in Emacs!
> 
> 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.

There's nothing wrong with that approach, but once you learn the Emacs
stuff you probably won't bother. At least that's been my experience.

[...snip...]
> > 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.

Right. One of my current docs, mirror-tutorial, will probably end up
around 2000 lines.

> > But for what we do, the FDP
> > suggests that you stick with tutorials that can be completed by one
> > person without too much hassle. If you think your hardening guide is
> > going to be much longer than 6-8 sections of a few pages each, then you
> > might be better off writing an outline and posting it to Bugzilla and
> > the list, to solicit more writers.
> > 
> 
> 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.

*nod* The great thing about using DocBook is that your content always
drives, and you don't have to worry about presentation. I've been
working by making an outline using just sections and titles, and filling
them in as I go. If I think of something along the way, I just make a
comment note <!-- FIXME: xxx... -->, rearrange sections as needed, and
so forth.

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

Glad you asked. Did you know that you can see a list of all open issues
for fedora-docs, as bugs in Bugzilla? Here's what I use for a query.[1]

http://bugzilla.redhat.com/bugzilla/query.cgi?query_format=&short_desc_type=allwordssubstr&short_desc=&product=Fedora%20Core&component=fedora-docs&component_text=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&long_desc_type=allwordssubstr&bug_file_loc_type=allwordssubstr

Bug 129911, it turns out, is the Installation Guide bug. Read that bug;
drop a line to the list and a comment in that Bugzilla bug about what
you're interested in doing.

> > That's just a suggestion, because it seems to me that security and
> > hardening is a somewhat open-ended topic, while installation is somewhat
> > self-limiting, and therefore easier to tackle first. A hardening
> > tutorial (or even a larger Security Guide) is a great idea, I just
> > question the priority.
> 
> True.  However, being a security engineer, I tend to place a great deal
> of value on security and it's implementation.

Absolutely. I should have been more clear: <opinion>Although security is
*very* important, producing a Security Guide is *less* important than an
Installation guide right now.</opinion>

[...snip...]
> > > Finally, once I get documents complete, what's the best way to submit
> > > stuff to my editor?  CVS?  Bugzilla?  Email?  What items should be
> > > included in the submission?
> > 
> > The best way to do it IMHO is to submit a tarball of the XML stuff to
> > Bugzilla, e-mail the list (maybe CC the editor), and point to the bug.
> > Or, if you have a private web site, you can use that to serve out the
> > XML source, but make sure the site clearly marks the document as a draft
> > that is not official.
> > 
> > Typically, you will want to write your document in a subfolder of the
> > fedora-docs/ folder you downloaded through CVS. For instance, I have a
> > ~/fedora-docs/usb-hotplug-tutorial/ folder, which contains a Makefile
> > and usb-hotplug-tutorial-en.xml, the XML source. Just tarball your
> > document by sitting in the fedora-docs/ folder and:
> > 
> >   tar czf my-tutorial.tar.gz my-tutorial/
> > 
> > Then any editor can simply pop the tarball out into the fedora-docs/
> > folder and have it automagically work for building.
> > 
> > > Thanks for hand-holding me right now.  Once I get the hang of it, things
> > > should be a little easier, and I should be a little more prolific. 
> > > After looking at the Doc Guide, writing in emacs/XML doesn't seem so
> > > daunting, so hopefully that won't be as much of an issue as I continue.
> > 
> > Believe me, I know JUST where you're standing now, I'm only a few feet
> > away on the other side of the hedge row. I occasionally glimpse Karsten
> > and Dave P., yonder over the hill. Sometimes they throw things. *BONK*
> 
> I'll post my outline to the bug, and maybe people will have some
> suggestions on sections to add.  My focus for this doc, has been to use
> Fedora "native" utilities to accomplish the task at hand (securing your
> system).  Introducing third party tools would increase the scope of the
> document, and may require additional authors, but I doubt it.  ;)

This is a fine idea. And I would say, FWIW, that your focus on using the
utilities in the distribution is *absolutely* the right way to go for
official FDP docs. There are way too many sites that solve problems in
Fedora Core by downloading a third-party utility, rather than using some
of the existing tools. In many cases, it's hard to tell whether that's
because the third-party tool is actually better, or if the author simply
doesn't know how to use what's already available. As the "official"
documentation site we should aim for helping people understand all the
goodies that come right out of the box.

> I already feel like I'm getting used to the tags, and having written
> HTML for almost 7 years, I should be able to slip right into it.
> 
> Thanks again for the tips and the list's patience.  ;)  

Thanks for your time and dedication -- that's on behalf of everyone, I'm
sure. The project is what we make of it, no more, no less! :-)  

-- 
Paul W. Frields, RHCE