Hardening Doc Preview

Sat Sep 4 22:36:49 UTC 2004

On Sat, 2004-09-04 at 21:37, Paul W. Frields wrote:
> On Sat, 2004-09-04 at 09:04, tuxxer wrote:
> > Hey guys.
> > 

<SNIP>

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

I think that it just implies that the author is aware, that his way
isn't the only way.  But that's also a matter of perspective, and
nuance.  

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

Generally a good practice.

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

Never used any of the linux spell-checking utilities before.  Guess
now's as good of a time as any to learn.  ;)

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

Cool....wasn't sure if those were "standard" entities, or ones that you
had customized in.

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

Understood and agreed.  However, I think that there is some value in
glossing over certain procedures (or re-presenting them) which might
otherwise be covered elsewhere, and thus referenced in your document. 
Continuously referencing other material makes the document
discontinuous, and sometimes difficult to read.  Overuse can even render
your document useless to the "average" user.  You end up with a document
like:

How to harden:

Accomplish this task described in this other document:

http://foo.doc.com/first_ref/

Then accomplish the task described in this other document: 

http://foo.doc.com/second_ref/ 

Then accomplish the task described in this other document: 

http://foo.doc.com/third_ref/ 

Then accomplish the task described in this other document: 

http://foo.doc.com/fouth_ref/ 

etc., etc. ad nauseum.....

You're not really providing the reader with a tutorial, just a list of
links that they probably could have found on some Joe Schmoe's website
hosted out of his garage.  ;)

Now if the document could be included (as an entity???), so that work
isn't duplicated, but your document actually contains the same
instructions, that might have value.  Then the reader is presented with
all of the information needed in one, concise location, that flows from
the beginning of the process to the end.  Sure, there might be some
duplication of data within the document project as a whole (100,000 ft.
view), but that duplication is only in the presentation of the data, not
the development or storage of the data.  From the reader's perspective,
I would think that this approach would be orders of magnitude more
valuable, than having a document that had a bunch of links for every
other section.  If I wanted a list of links I would just use Google
(which is usually the case anyway).  I also think that the FDP should be
the defacto standard in documentation for the distribution, and thus,
the most complete, most readable, and most informative.  In other words,
why would I read (and follow) the FPD's document for a particular
project, if charliesfedoradocs.com has a document that has everything I
need in one single place?  (Rhetorical question. ;)

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

OK, so how do you say ... "This section is important.  However, THIS
section is REALLY important." ??  For example, while it IS important to
update your system, I've actually been in situations where NOT being
updated has been a good thing.  Certain vulnerabilities are found to
work in certain versions of certain applications, but earlier versions
(and sometimes later ones) may not necessarily be vulnerable.  So how
would I emphasize that updating is important, but it's MORE important
that the user close off other vectors of attack (network penetration,
file system vulnerabilities, unmanaged users, etc.)?

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

I think this is a matter of semantics, and could just be a matter of
"learning the lingo".

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

Again, a matter of nuance....  "Important!" reads as a lot more
important to me than "Important".

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

Generally a good practice.  I am from the southeast, so it tends to come
a little too naturally sometimes.  ;)

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

<SNIP>

And all very valid points.  I was going to say in my initial post (but
finally decided against it) that I have a hard shell for criticism,
since this is my first attempt at any sort of official documentation,
and really any technical writing, as well.  I've written PLENTY of SOPs,
but the ones I write have to be designed for
Joe-Blow-I-Can't-Even-Spell-Linux types.  They are also maintained with
a very limited audience scope, so I guess I'm allowed certain
"freedoms"  (read:  I'm the only one writing anything, so
standardization is pretty much what I say it is at this point [for MY
environment ;) ]).

> 
> = = = = =
> [1] update-tutorial:
> https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131131
> 
> -- 
> Paul W. Frields, RHCE   (greedily appropriating Karsten's footnotes)
-- 
--

tuxxer <tuxxer(a)cox(dot)net>

     <== tuxxer's gpg key fingerprint ==>
57EB F948 76AE 25BC E340  EFA9 FAF6 E1AC F1E1 1EA1
-------------- 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/20040904/85313785/attachment.sig>