Hardening Doc Preview

[Paul W. Frields]

On Sat, 2004-09-04 at 09:04, tuxxer wrote:
> Hey guys.
> 
> I'm posting a draft version of what I've got so far of the hardening doc
> in my own web-space.  It's not much, but it will be updated rather
> randomly, as I get chances to work on it.  There isn't a "draft"
> statement on it at the moment (other than the title), but I'm working on
> that, and it will be there shortly.
> 
> 
> Link:  http://members.cox.net/tuxxer/
> 
> I'll be posting the XML to the bug, once I've finished chapter 1.
> 
> Please feel free to comment, critique, shred, etc.  

It's good to see you're blazing ahead! I will try and fix up an XML
patch for you that will make these points, but I am committing some of
them to the list in the hopes they will help others who are lurking
and/or working on documents of their own. I will readily admit to being
guilty of these same problems from time to time, and I'm marking the
suggestions below accordingly. I try to catch the problems before they
leave my repo, but as Karsten will testify, that doesn't always happen!
I am going to add these issues to my Style TODO as well.

1. Don't overuse "most of," "typically," "usually," "many." These water
down your instructions and make the tutorial sound wishy-washy, as if
you're trying to CYA. A document the length of a typical tutorial can't
possibly cover every single case, and shouldn't try. Your tips should
adequately cover a stock installation of Fedora Core, in the present
version. Don't state this beyond the context of your document's goal(s);
the fact that it's going to be an official Fedora Doc makes this the
case. (Guilty)

2. Don't use first person at all: "I," "me," "my," "mine," "we," "our,"
"ours." Also do not use "his or her," "his/her," "he or she," "s/he."
Reformulate your sentence to eliminate it.

3. Use ispell (or whatever spelling checker you have available) before
you post a new version. That simply saves the editor a little time. :-)
(Guilty)

4. Use active voice. "Issue this command," not "The XXX command needs to
be run." The tutorial tells the user how to do something, and should
give instructions clearly and concisely. (GUILTY!)

5. Don't use abbreviations like FC2 or FC. Instead, use the entity &FC;
(which inserts the words "Fedora Core" thanks to our entities) with or
without &FCVER; (the version number). Put a space between &FC; and
&FCVER; like this:

    &FC; &FCVER; provides firewall capabilities...

6. This is a matter of content: Don't cover updates (up2date or yum) in
a tutorial about system hardening, beyond stating the user should pull
system updates. Direct the reader to other resources. If every tutorial
author does this, the aggregate wasted time will be substantial. There
may not be an "official" update-tutorial to link to right now, but
that's fine. Simply leave a place marker; there's a tutorial on the way
for that subject. When it shows up, add a <ulink> to it in your
document.

(*** NOTE: I think this brings up an interesting side point, which is
that the yum/up2date tutorial currently in process [1] needs some
editorial lovin'. Once that's done, any author can point to the finished
document at the &FDPDOCS-URL; site. That's what this tutorial should do.
***)

7. Leave out statements like "One of the most important things to do is
to mind your P's and Q's." If it's important, the reader expects it to
be in your tutorial. The converse is also true: if it's in your
tutorial, the reader expects it is important, especially if you use a
whole section for it. Merely state, "Mind your P's and Q's." Then
elaborate as required. If the whole section concerns how to mind one's
P's and Q's, you may be able to leave this sentence out entirely.
(Guilty)

8. When you direct readers, use correct words for the actions they
should take. Users do not "go to" the Main Menu -> Foobar. They either
click on Main Menu and then click on Foobar, or from the Main Menu they
select Foobar. (I would argue the latter is better, because some people
don't use a mouse even in the GUI. I actually avoid it depending on what
I'm doing at the time.)

9. Avoid punctuation in your titles for sections or admonitions --
except for commas where demanded. ("Important!:", "Note:".) Instead,
just use the title itself ("Important"). It is helpful (and encouraged)
to use a title that says something about the admonition comment, such as
"Stop services." This is a minor style point, but your editor will
likely fix it if you don't.

10. Avoid contractions when possible. They can be confusing to readers
for whom English is not a first language. (Guilty)

11. Avoid slashes "/" in titles or in your prose (except in <filename>
or other appropriate context, of course). Use "and" or "or."

That's a long list, but not too difficult to learn for your writing. I
think these are all minor criticisms, and hope you'll take them in the
constructive spirit in which they're offered. Also, visit the following
URL's and bring your document in line with their recommendations.
Following these guidelines will make your document stronger and more
professional looking:

http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00307.html
http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html

There are others in the archives but I didn't have time to track them
all down. They will certainly be collected for the style portion of the
Docs Guide as soon as I have time to do that. I'm hoping to start this
weekend.

= = = = =
[1] update-tutorial:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131131

-- 
Paul W. Frields, RHCE   (greedily appropriating Karsten's footnotes)