I'm using this wiki commit message as an opportunity to talk about some
problems I'm seeing in composition and style that writers should keep in
mind. This hopefully will benefit a bunch of folks...
On Sat, 2007-05-19 at 14:21 +0000, fedorawiki-noreply@xxxxxxxxxxxxxxxxx
wrote:
> The three major desktop managers included with Fedora 7 are:
>
> - * GNOME - previously the desktop manager installed by default
> + * GNOME - previously the default desktop manager, still an
> excellent choice
> - * KDE - a desktop manager known for its large collection of
> applications and great customization
> + * KDE - a desktop manager known for its large collection of
> applications and great customization features
> - * Xfce - an excellent desktop manager for legacy PCs and laptops,
> due to its low-memory requirements
> + * Xfce - an excellent desktop manager for legacy PCs and laptops,
> due to its low-memory requirements, with great add-on features
PROBLEM: Making judgment calls in writing. Do not classify things as
"good," "bad," "ugly," or anything else subjective. Do not show bias or
qualitative comparison.
> Many others are also available, some of which can be installed from
> Fedora's extensive library of applications, or ''repositories''.
>
> Before describing the desktop managers in greater detail, it's good
> to know that applications written for one desktop manager work with
> other managers with very few exceptions.
>
> - For instance, '''konqueror''' is a combination web browser/file
> manager which is part of the KDE suite of applications. Although a KDE
> application, Konqueror also runs seamlessly with the GNOME and Xfce
> desktop managers available with Fedora.
> + For instance, '''Konqueror''' is a combination web browser/file
> manager which is part of the KDE suite of applications. Although a KDE
> application, Konqueror also runs seamlessly with the GNOME and Xfce
> desktop managers available with Fedora.
PROBLEM #1: Do not use "/" in writing, such as "he/she," "and/or", or
any other construct. Some languages do not allow this construct --
therefore avoid it. Use "and" or "or," or simply restructure the
sentence to avoid this issue.
PROBLEM #2: The word "combination" is unnecessary here. By using the
word "and" the implication is that the application is indeed a
combination, so fixing Problem #1 will take care of this issue.
PROBLEM #3: Avoid adverbs where possible, since they often indicate
qualitative judgments (see above).
PROBLEM #4: Avoid misleading technical cues. "[A]vailable with Fedora"
seems to imply that the user's Fedora system comes with these desktop
managers installed, which often may not be the case.
SOLUTION: "Konqueror is a web browser and file manager included in the
KDE suite of applications. Konqueror can also be used with the GNOME
and Xfce desktop managers."
> Another example is the '''Open``Office.org''' office suite.
> Open``Office.org applications run on the three major desktops shipped
> with Fedora. In fact, once an application is in use, it's sometimes
> difficult to tell which desktop manager is active.
PROBLEM #1: Avoid contractions such as "it's."
PROBLEM #2: The use of "In fact" here is unnecessary and implies that
we're not being factual in other parts of the document, which I would
assume is not the case. :-)
> Remember, Fedora Linux is all about choice. There are many
> applications from which to choose in order for Fedora users to browse
> the World Wide Web, write and edit documents, and display and edit
> photos.
PROBLEM #1: Telling the user "Remember" is an unnecessary instruction.
Furthermore, there is a qualitative judgment that "Fedora Linux [sic] is
all about choice." Rephrase this to remove these issues.
PROBLEM #2: The phrase "in order" (such as "in order to" or "in order
for") is usually redundant. Avoid it whenever possible.
PROBLEM #3: Avoid passive voice to make sentences stronger.
SOLUTION: "Fedora offers an array of choices for performing many common
tasks. Users may choose from many applications to browse the World Wide
Web, write and edit documents, and display and edit photos."
> - This guide describes the most common applications which are
> installed. Other applications are also described as equally good
> alternatives to the "default" applications. In fact, the idea of a
> "default application" is becoming rather meaningless, as the ease of
> installing Fedora applications increases.
> + This guide describes the most common applications which are
> installed. Other applications are also described that are equally good
> alternatives to the "default" applications. In fact, the idea of a
> "default application" is becoming rather meaningless, as the ease of
> installing Fedora applications increases.
PROBLEM #1: Qualitative judgments ("equally good alternatives," "rather
meaningless.")
PROBLEM #2: The FDUG's objective is to describe the default
installation of Fedora. Avoid mission drift.
SOLUTION: "This guide describes the most commonly installed desktop
applications."
(And then ensure the FDUG actually *DOES* this.)
--
Paul W. Frields, RHCE http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
Fedora Project: http://fedoraproject.org/wiki/PaulWFrields
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
