tuxxer wrote:

<snip>

I am not sure if peer review is sent to the mailing list or directly to just the author. Some suggestions are questionable due to my inexperience in precedence set by the editors and authors before me. So the editors may have better ideas on the concepts. There may even be a guide pertaining to such questions; if not, it may behoove us to generate one.

But here is a few technical suggestions for chapter #1 if you are still in the market for them:

Well most are technical -- a few may be preference. :P

First let me state that you have done a very good job of generating meaningful content. The complexity yet readability of the document is very evident from my first review. Most items I comment on are nit-picking and do not in anyway detract from the quality job you have done! Hopefully you can find value in my recommendations so that you can continue to author quality works such as this.

Good job!!! :)

1.1.2.1::

1) If I may, I would suggest utilizing the --lsign-key command rather than --sign-key for various reasons.

Unless you decide to introduce to the end-user a sufficient amount of personal verification of the owner(s) of the key; you should not "globally" sign the kernel.org public-key.

If the end-user were to accidentally do the following: gpg --send-keys

Then ALL keys --- including the incorrectly signed key --- would be exported to the default keyserver. This undermines the trust model used by the specific public-key, and the gpg public-key cryptosystem itself.

Instead a "local signature" is advised. This type of signature introduces a "local" verification of the end-users trust level and thats it. If the end-user executed the same command as above; the local signature would not be exported. Hence, keeping the "global" integrity of the kernel.org public-key intact.

2) This section, nor does the kernel.org hyperlink, discuss any verification of the public-key that is being imported. i.e. verifying the key fingerprint

This step needs to be performed prior to signing it with the "Bogus key". Otherwise, the end-user is blindly signing the imported public-key. Which actually should be done prior to the actual importation into the end-users recently generated keyring. Verify the integrity of the public-key, than import it into the keyring. Finally, perform the trust-level verifications as needed by the scenario at hand, and sign the key to rid the end-user of that annoying trust warning.

3) Personal preference --- I would extract only the relevant data from the output of "ftp ftp.kernel.org". Alot of the data is fluff, seems irrelevant to the process at hand; and detracts from the good step-by-step process description that you are providing. ;)

1.1.2.2::

1) The output contained in the "ftp download.fedora.redhat.com" process is similar to the above #3 comment. Some output seems irrelevant.

2) The md5sum process comprised of the last three(3) outputs can be executed with a single sequence of commands:

md5sum -c MD5SUM 2> /dev/null | grep 'FC3-i386-disc1.iso'

with an output of:

FC3-i386-disc1.iso: OK

The redirection of stderr is necessary because multiple packages are contained within the checksum file, however this is much simpler for the end-user. Traversing back and forth from two 32 hexadecimal characters sequences to verify authenticity is a tedious job.

If later chapters include similar checks for individual packages; the above command can be simplified to the following:

md5sum -c package-1.0-fc3.md5

3) If you decide not to use the above change #2; then the statement "If the hexadecimal number in the first column matches the hexadecimal number output..." should be changed to:

"If the 32 digit hexadecimal character sequence in the first column matches the 32 digit hexadecimal character sequence output..."

This correctly identifies the process as not just containing numerical digits.

1.2::

1) Generally it is always recommended to utilize sudo rather than directly changing to the EUID of 0; regardless of the number of commands to be executed. This greatly reduces the chance(s) that an irrecoverable accident can occur from utilizing superuser permissions. Given the experience level of some of the end-user(s) of this document; it may be advisable to change this statement accordingly.

2) The sentence "This file allows you to set up commands and aliases that are allowed through sudo, and which users are allowed to run them." should be altered to identify that you the end-user can also regulate the authorized machine from which a particular user can execute a specific command.

3) The document topic is about "hardening a fedora installation" but the example output of /etc/sudoers utilizes the most insecure alias available under the sudo system. I would definitely alter this to a more restrictive example.

1.3:: This chapter is well done. Kudos --- Charles

1.4:: 1) Alter the following sentence "Make sure that you have all of the updates." to read "Make sure that you have all of the most current updates."

The reasoning behind this is due to the capability of the end-user to utilize "delta" rpms.

With reference to "delta" meaning a calculated difference between two specific versions of a package.

By using this update scheme, the end-user can successfully update to the most current version of a package without the need for any intermediary patches for a given package. For example:

Under normal update procedures, if a user has the following initial release installed ---- package-1.0.12.fc3.rpm and wants to update to the most current version package-1.0.15.fc3.rpm the end-user must download ALL of the following ---- package-1.0.13.fc3.rpm, package-1.0.14.fc3.rpm and package-1.0.15.fc3.rpm

However, in a delta update system; the end-user must only download a single update package. I noticed mailing list traffic pertaining to beta deployments of delta fedora repositories being tested over the last month. Other distributions utilize this scheme and would expect that in the near future this will be the recommended update procedure. It may even behoove the end-user to be aware of this capability regardless of utilization stability within fedoras update repositories.

This seems to be a preemptory change due to documentation of the so-called "standard" installation. It may very well be considered for future use; but I felt it needed to be addressed for possible inclusion.

2) Alter the sentence "This is indicated by the red exclamation point icon in the upper right hand corner of the screen, on the panel." to the following "This is indicated by the red exclamation point icon located in the upper right hand corner of the Gnome panel." Seems to flow a little better.

3) Personal preference --- Alter the sentence "Follow the instructions in the follow on dialogs to update your system" to "Follow the instructions in the subsequent dialogs presented to update your system".

1.5:: This chapter looks very good!!! Well done. ;)

1.6.1::

1) This section does not notify the end-user of the "administrative privileges" dialog that is presented.

2) The "upper-right pane" term is identified as actually being a "Text View" in interface designing. What is the correct procedure for this? Pane seems more descriptive, yet it is not the proper terminology.

This goes for all gui items. i.e. check box --> check button

????????

3) The important admonition statement "stopping that particular service will inhibit any functionality you expect from the system" should be altered to "stopping that particular service will inhibit any functionality you do not expect from the system".

1.6.2::

1) The note admonition seems redundant. In previous sections, changing to an effective uid of 0 had already been reviewed. As well, the previous sections utilizing the "sudo" command did not contain such a note.

2) The statement " If you are running in command line only mode (runlevel 3)" incorrectly states available runlevels. Runlevels 1,2 and 3 are all of the console persuasion.

1 - is single-user mode --- only root access from the local tty console. No pseudo ttys. 2 - is multi-user mode without networking --- various user logins authorized from from the local console terminal. 3 - is multi-user mode with networking --- various user logins authorized from from the any console terminal. Local and pseudo included.

Although, runlevels 1 and 2 are normally utilized for debugging and administrative purposes only; it is still a resource that may be utilized by the more experienced end-users.

3) There is reference to changing permissions of file in this section. It would be a good idea to go over this topic. Otherwise, the inexperienced end-user may inadvertently chmod this script to being readable by the "other" user class ---- and god forbid executable as well.

4) Also there is an inconsistent transfer of uid's on this page. The end-user starts out as the uid of a normal user ---- say 501; and is transitioned to a uid of 0 with regards to execution of the generated script.

5) The last statement incorrectly identifies only runlevels 3 and 5 as multi-user runlevels. However, runlevel 2 is as well.

1.7::

1) If I might suggest, place a warning in this section stating that the end-user is recommended to make a backup of the /etc/passwd file and the /etc/shadow files.

Which if implemented, needs to also recommend the proper placement of such a backup. As well as, any recommended cryptographic procedures to secure the backup against compromise.

i.e. encryption and digital signing of the backup using the new gpg keyring. ;)

2) " Remember the list of services that you disabled." is a question.

1.7.1::

1) The authorization tip admonition should identify the referenced dialog box as "administrative privilege dialog box" or as the "userhelper dialog box interface to PAM". Or something such as this. What is the precedence of the fedora-docs team prior to this?

On Wed, 2005-05-11 at 00:18 -0500, Thomas Jones wrote:

tuxxer wrote:

<snip>

I am not sure if peer review is sent to the mailing list or directly to just the author. Some suggestions are questionable due to my inexperience in precedence set by the editors and authors before me. So the editors may have better ideas on the concepts. There may even be a guide pertaining to such questions; if not, it may behoove us to generate one.

But here is a few technical suggestions for chapter #1 if you are still in the market for them:

Well most are technical -- a few may be preference. :P

First let me state that you have done a very good job of generating meaningful content. The complexity yet readability of the document is very evident from my first review. Most items I comment on are nit-picking and do not in anyway detract from the quality job you have done! Hopefully you can find value in my recommendations so that you can continue to author quality works such as this.

Good job!!! :)

1.1.2.1::

1. If I may, I would suggest utilizing the --lsign-key command rather

than --sign-key for various reasons.

Unless you decide to introduce to the end-user a sufficient amount of personal verification of the owner(s) of the key; you should not "globally" sign the kernel.org public-key.

If the end-user were to accidentally do the following: gpg --send-keys

Then ALL keys --- including the incorrectly signed key --- would be exported to the default keyserver. This undermines the trust model used by the specific public-key, and the gpg public-key cryptosystem itself.

Instead a "local signature" is advised. This type of signature introduces a "local" verification of the end-users trust level and thats it. If the end-user executed the same command as above; the local signature would not be exported. Hence, keeping the "global" integrity of the kernel.org public-key intact.

2. This section, nor does the kernel.org hyperlink, discuss any

verification of the public-key that is being imported. i.e. verifying the key fingerprint

This step needs to be performed prior to signing it with the "Bogus key". Otherwise, the end-user is blindly signing the imported public-key. Which actually should be done prior to the actual importation into the end-users recently generated keyring. Verify the integrity of the public-key, than import it into the keyring. Finally, perform the trust-level verifications as needed by the scenario at hand, and sign the key to rid the end-user of that annoying trust warning.

3. Personal preference --- I would extract only the relevant data from

the output of "ftp ftp.kernel.org". Alot of the data is fluff, seems irrelevant to the process at hand; and detracts from the good step-by-step process description that you are providing. ;)

1.1.2.2::

1. The output contained in the "ftp download.fedora.redhat.com" process

is similar to the above #3 comment. Some output seems irrelevant.

2. The md5sum process comprised of the last three(3) outputs can be

executed with a single sequence of commands:

md5sum -c MD5SUM 2> /dev/null | grep 'FC3-i386-disc1.iso'

with an output of:

FC3-i386-disc1.iso: OK

The redirection of stderr is necessary because multiple packages are contained within the checksum file, however this is much simpler for the end-user. Traversing back and forth from two 32 hexadecimal characters sequences to verify authenticity is a tedious job.

If later chapters include similar checks for individual packages; the above command can be simplified to the following:

md5sum -c package-1.0-fc3.md5

3. If you decide not to use the above change #2; then the statement "If

the hexadecimal number in the first column matches the hexadecimal number output..." should be changed to:

"If the 32 digit hexadecimal character sequence in the first column matches the 32 digit hexadecimal character sequence output..."

This correctly identifies the process as not just containing numerical digits.

1.2::

1. Generally it is always recommended to utilize sudo rather than

directly changing to the EUID of 0; regardless of the number of commands to be executed. This greatly reduces the chance(s) that an irrecoverable accident can occur from utilizing superuser permissions. Given the experience level of some of the end-user(s) of this document; it may be advisable to change this statement accordingly.

2. The sentence "This file allows you to set up commands and aliases

that are allowed through sudo, and which users are allowed to run them." should be altered to identify that you the end-user can also regulate the authorized machine from which a particular user can execute a specific command.

3. The document topic is about "hardening a fedora installation" but the

example output of /etc/sudoers utilizes the most insecure alias available under the sudo system. I would definitely alter this to a more restrictive example.

1.3:: This chapter is well done. Kudos --- Charles

1.4::

1. Alter the following sentence "Make sure that you have all of the

updates." to read "Make sure that you have all of the most current updates."

The reasoning behind this is due to the capability of the end-user to utilize "delta" rpms.

With reference to "delta" meaning a calculated difference between two specific versions of a package.

By using this update scheme, the end-user can successfully update to the most current version of a package without the need for any intermediary patches for a given package. For example:

Under normal update procedures, if a user has the following initial release installed ---- package-1.0.12.fc3.rpm and wants to update to the most current version package-1.0.15.fc3.rpm the end-user must download ALL of the following ---- package-1.0.13.fc3.rpm, package-1.0.14.fc3.rpm and package-1.0.15.fc3.rpm

However, in a delta update system; the end-user must only download a single update package. I noticed mailing list traffic pertaining to beta deployments of delta fedora repositories being tested over the last month. Other distributions utilize this scheme and would expect that in the near future this will be the recommended update procedure. It may even behoove the end-user to be aware of this capability regardless of utilization stability within fedoras update repositories.

This seems to be a preemptory change due to documentation of the so-called "standard" installation. It may very well be considered for future use; but I felt it needed to be addressed for possible inclusion.

2. Alter the sentence "This is indicated by the red exclamation point

icon in the upper right hand corner of the screen, on the panel." to the following "This is indicated by the red exclamation point icon located in the upper right hand corner of the Gnome panel." Seems to flow a little better.

3. Personal preference --- Alter the sentence "Follow the instructions

in the follow on dialogs to update your system" to "Follow the instructions in the subsequent dialogs presented to update your system".

1.5:: This chapter looks very good!!! Well done. ;)

1.6.1::

1. This section does not notify the end-user of the "administrative

privileges" dialog that is presented.

2. The "upper-right pane" term is identified as actually being a "Text

View" in interface designing. What is the correct procedure for this? Pane seems more descriptive, yet it is not the proper terminology.

This goes for all gui items. i.e. check box --> check button

????????

3. The important admonition statement "stopping that particular service

will inhibit any functionality you expect from the system" should be altered to "stopping that particular service will inhibit any functionality you do not expect from the system".

1.6.2::

1. The note admonition seems redundant. In previous sections, changing

to an effective uid of 0 had already been reviewed. As well, the previous sections utilizing the "sudo" command did not contain such a note.

2. The statement " If you are running in command line only mode

(runlevel 3)" incorrectly states available runlevels. Runlevels 1,2 and 3 are all of the console persuasion.

1 - is single-user mode --- only root access from the local tty console. No pseudo ttys. 2 - is multi-user mode without networking --- various user logins authorized from from the local console terminal. 3 - is multi-user mode with networking --- various user logins authorized from from the any console terminal. Local and pseudo included.

Although, runlevels 1 and 2 are normally utilized for debugging and administrative purposes only; it is still a resource that may be utilized by the more experienced end-users.

3. There is reference to changing permissions of file in this section.

It would be a good idea to go over this topic. Otherwise, the inexperienced end-user may inadvertently chmod this script to being readable by the "other" user class ---- and god forbid executable as well.

4. Also there is an inconsistent transfer of uid's on this page. The

end-user starts out as the uid of a normal user ---- say 501; and is transitioned to a uid of 0 with regards to execution of the generated script.

5. The last statement incorrectly identifies only runlevels 3 and 5 as

multi-user runlevels. However, runlevel 2 is as well.

1.7::

1. If I might suggest, place a warning in this section stating that the

end-user is recommended to make a backup of the /etc/passwd file and the /etc/shadow files.

Which if implemented, needs to also recommend the proper placement of such a backup. As well as, any recommended cryptographic procedures to secure the backup against compromise.

i.e. encryption and digital signing of the backup using the new gpg keyring. ;)

2. " Remember the list of services that you disabled." is a question.

1.7.1::

1. The authorization tip admonition should identify the referenced

dialog box as "administrative privilege dialog box" or as the "userhelper dialog box interface to PAM". Or something such as this. What is the precedence of the fedora-docs team prior to this?

Tom,

Just a quick reply, thanks for all of your comments. You're more complementary than anyone so far! ;-)

It's late for me, but I will provide a more detailed reply tomorrow.

Thanks again for replying, I'm ready to get this edited and published.

-Charlie

On Thu, 2005-05-12 at 13:41 -0700, Karsten Wade wrote:

On Wed, 2005-05-11 at 06:30 +0000, tuxxer wrote:

...

Thanks again for replying, I'm ready to get this edited and published.

How about moving the document into Fedora CVS? It will make the editing easier, since we can edit the XML directly and you can see the changes in the commit log (or using cvs diff).

I think the only thing you personally have left to do is to register

https://admin.fedora.redhat.com/accounts/

Done.

and read the short usage guidelines

http://www.fedoraproject.org/wiki/DocsProject_2fCvsUsage

Done.

then we'll get your account active and you can 'cvs import' away.

General comment to everyone about CVS ... don't worry if you are new to version control, you will soon learn to love it. The best feature is that you can always roll back whatever changes you make, so mistakes are no big deal. ;-)

• Karsten

I'm a complete CVS newbie, so this should be interesting. When will I know that I have the access to import? I haven't been able to get anonymous access for a while, but I'm assuming this user access will supercede that.

-Charlie

Uttered Karsten Wade kwade@redhat.com, spake thus:

The anonymous access should be working, I've tested it a few times, but the server has changed since originally. Doesn't matter for you anymore, though. :)

I've checked it also because I'm updating all "common/cvs-en.xml", pending sticksters's consent.

Cheers

On Fri, 2005-05-13 at 18:22 +0000, tuxxer wrote:

On Fri, 2005-05-13 at 08:02 -0700, Karsten Wade wrote:

...

As soon as you join the group and the CVS admin approves the group, within an hour you will have full CVS access to import and otherwise write to CVS.

I got this when I tried adding myself to the group:

'Add' action denied. You may need to become a member of the cla_done group first.

Did you go through the CLA process (second link on the Accounts page)? IIRC, when you complete the step, your account is added to the cla_done group automagically and almost instantly.

On Fri, 2005-05-13 at 00:49 +0000, tuxxer wrote:

On Wed, 2005-05-11 at 00:18 -0500, Thomas Jones wrote:

...

1.6.1::

1. This section does not notify the end-user of the "administrative

privileges" dialog that is presented.

Isn't this covered by the "Access Note"? Or are you talking about something else?

...

2. The "upper-right pane" term is identified as actually being a "Text

View" in interface designing. What is the correct procedure for this? Pane seems more descriptive, yet it is not the proper terminology.

This goes for all gui items. i.e. check box --> check button

????????

OK, I can understand the reasoning there, but IMHO, that's the kind of verbiage that can alienate a complete newbie. (This is obviously a small example.) Perhaps this is more of a style question that could be addressed by someone like, Paul (the Style-Guide author ;-).

You rang? :-D I agree about the alienation factor, but it's equally important not to bind the documentation unnecessarily to a particular interface design that might change, or might be affected by certain localizations. Plus, it's unnecessarily wordy. The dialog is not so complicated that even the average newbie needs to be told *where* to locate the service description.

If this tutorial were instead documentation for the Service Configuration tool that was written as part of a comprehensive system engineering process, I would say that even more description was called for. This document is, however, merely a tutorial in which the Service Configuration tool plays a small but necessary part. Therefore, in the interests of brevity (and reader attention), I would eliminate the wordiness, so the sentence would read:

"For each service listed, the Service Configuration utility will display a short description, and the current status and process ID (PID) of the service, if it is running."

...

3. The important admonition statement "stopping that particular service

will inhibit any functionality you expect from the system" should be altered to "stopping that particular service will inhibit any functionality you do not expect from the system".

This is a tuffie - I think the whole thing could be worded better.

Check the Style chapter in the Documentation Guide, which addresses a number of the problems in the admonition. I'll present some highlights here as an example. Use these as guidance to help you tighten your own writing "as you go." Remember that good writers constantly edit themselves. (I have to, because Karsten wields a mean dead trout. My face still stings....)

I'm not convinced this whole thing should be an admonition. If you tell a reader to follow a procedure for a task, make that procedure part of the text. Admonitions should only be used to bring a particular *side effect* of the procedure (or an operator error) to the reader's attention.

1. Avoid gerunds. <pedantic>A gerund is the "-ing" form of a verb, for anyone who didn't know already.</pedantic> In almost all cases, a gerund is a harbinger of other style boo-boos, such as passive voice and excessive wordiness.

2. "Be sure to" is almost always superfluous. Tell the user what to do: "Stop a service before you disable it." Notice this also fixes an instance of problem #1.

3. The second sentence is 33 words long, which is too long. See 8.2.2 in the Documentation Guide ("Golden Rule 1").

4. If you give an instruction, tell the user how to follow it. Do not assume that every member of your audience knows the recommended procedure.

5. Don't use the type of admonition as an admonition title. Instead of "Important," use a descriptive title.

[6. I'm not sure this counts as style, nor if it's actually valid. In what cases would you have to reboot a system, if you failed to stop the service before disabling it? It's early in the morning, please be kind to the sleep-deprived. In any case, the fact that I'm wondering about it means that it probably needs to be more detailed.]

Here's a possibly improved version. Note that this is not DocBook XML, I'll leave the markup to you. The main part of the text is not an admonition. The admonition that I present below may not be required if my concern in #5 above is valid.

"Stop a service before you disable it, to immediately observe the effects on your system. To stop a service using the Service Configuration tool, select the service and then click the Stop button. The service stops immediately, or in the event of an error, the Service Configuration tool displays an error dialog.

"[* Avoid Reboot If you do not stop a service before you disable it, you may have to reboot the system.]"

= = =

Now that I got that out of my system, nitpicky moment. Your use of the phrase "hexadecimal number," as in "compare the hexadecimal number on the left to the hexadecimal number on the right," is acceptable.

A series of symbols in the regex set [0-9] (what we call "digits") is a representation of a decimal number. A series of symbols in the set [0-9A-F] is a representation of a hexadecimal number. We eliminate the words "representation of" because an actual number cannot be written on paper, nor typed on a computer, nor displayed on a screen. An actual "number" is a cognitive construct. Any number you can read or write is a "representation of" a number. We take the phrase "representation of" as implied, because it is unnecessarily wordy, and perceptually obvious to the reader -- although it does engender interesting metaphysical discussions. (The *idea* of hexadecimal numbers may not be perceptually obvious to the reader, but that's a different issue entirely.)

You see, editing *is* a constant process! This is the last go round and I promise I won't do this again. Sorry all.

On Fri, 2005-05-13 at 08:27 -0400, Paul W. Frields wrote:

...

"For each service listed, the Service Configuration utility will display a short description, and the current status and process ID (PID) of the service, if it is running."

That should be:

"For each service listed, the Service Configuration displays a short description, and the current status and process ID (PID) of the service, if it is running."

Another style rule: Use present tense! :-)

The narrative should also describe the tool as it actually works. The SC tool doesn't display the descriptions unless you actually *select* a service. (I also made a typo and omitted a word.) Since the sentence would then be getting a little too long, it needs to be split, and in doing so, let's eliminate that gerund at the end too. By using an adjective instead, we can even improve the sentence flow to emphasize what the utility shows the reader. Remember that the end of a sentence is where the most "kinetic energy" is stored -- a phrase placed there has more "oomph" potential. Try this:

"When you select a service, the Service Configuration utility displays a short description. If the service is active, the utility also displays the current status and process ID (PID)."

All right, no more replies to myself on list. I'll just slap myself in the face quietly if I catch anything else wrong. :-)