Rough start...

['D@7@k|N&']

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:
> > I've been doing some work on the hardening tutorial and I've gotten to
> > the point where I have a few questions.
> > 
> > First of all, do I need to do anything to the bugzilla report to show
> > that work is actually being done on this guide?
> 
> You could put your timeline and/or milestones in there for when you
> expect to have certain things done. See previous threads, and Tammy and
> Karsten's process documents, for more on that.

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.  

> 
> > I've tried writing in emacs, and I feel like I'm fighting the program so
> > much that I haven't been able to write any of the actual tutorial.  So,
> > I did some work in Kate, and am trying to back port it with the XML tags
> > to make it fit the model.  I followed the steps in the Doc Guide for
> > setting up emacs, and I think I got it right, but tag completion, and
> > coloring, etc. doesn't seem to be really intuitive.
> 
> I felt the same way when I started. Push through, and try working on
> something that is *not* your actual document, so you don't feel pressure
> about "getting things done," and are free to simply try the features
> out. I think it's probably too much for people to try to memorize the
> whole chart of Emacs/psgml key bindings in the Doc Guide.
> 
> Here's what I did to start:
> 
> 0. Spend a couple days avoiding all editors except Emacs, no matter
> *what* I was doing, FDP or other work. Spent an hour or so on the Emacs
> tutorial to learn some basic keystrokes -- only a few of which I've
> actually memorized, but just enough so that I'm not completely flailing
> 100% of the time.
> 
> 1. Pull the .emacs stuff in the Doc Guide into my ~/.emacs file.

Did that.

> 
> 2. Download the CVS for fedora-docs, using the steps in the Doc Guide or
> on the front page of the FDP site.

Did that....

> 
> 3. Copy example-tutorial/ folder to foobar/ folder.

...yeah...
> 
> 4. Open up foobar/example-tutorial-en.xml in Emacs.
> 
> (A lot of times, I hit Alt+X, type "xml-mode" and hit ENTER to force XML
> mode, which makes some tag markup work better... do this as optional
> step 4B. I'm not sure if this is the "right" thing to do, but it stops
> psgml from acting strangely on tags that self-close, like <xref
> linkend="sn-some-target"/>.)
> 
> 5. Hit Ctrl+C, Ctrl+P to parse the DTD stuff at the top. Colors should
> appear shortly thereafter. 
> 
> NOTE: Like you, I don't really feel this is "intuitive," but then,
> neither is :wq in vi, or hitting Alt+F4 to close a GUI application.
> They're just things you have to learn. After you use a step enough, it
> will be second nature to you. (Not being preachy, just matter o' fact.

No worries.  Alt+F4 happens to not be that elusive for me; I've been hit
with enough adware/popups on my windows box that it's familiar.

> I've learned to accept that each time I learn a new keybinding in Emacs,
> it takes a few days of use to become habit. I can live with that!)
> 
> 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.

> 
> > Anyhow, I've taken a look at the CVS stuff, and thought that the Install
> > Guide my be a good one to use as an example, but that looks like a WIP. 
> > So, I took a look at the Doc Guide, and that's a little more complete. 
> > The layout of the Doc Guide implies that each chapter should be a
> > separate document.  Is this true?  Or, if you build one monolithic
> > document, will the Makefile parse all of the info correctly so that the
> > different chapters break out into different pages?
> 
> 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.

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

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

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

> 
> If you write a tutorial as an <article> as suggested in the Doc Guide,
> each first-level <section> will break out into a separate HTML page.
> Doing the "make html" just takes care of it. You only need to edit the
> DOCNAME of the document in the Makefile.

Finally figured that out, once I got things in order and was able to get
the 'make html' work.

> 
> > 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.  ;)


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.  ;)  

-- 
--
-=D at 7@k|N&=-
 
<== dataking's pgp ==>
9287 3334 03E4 965E 0D2D  F7CA A6E7 407C 1558 A263

-------------- 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/20040829/8084a5b6/attachment.sig>