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.)
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
