Bug 169895 - Writing style/grammar improvements for release notes
Writing style/grammar improvements for release notes
Status: CLOSED RAWHIDE
Product: Fedora
Classification: Fedora
Component: fedora-docs (Show other bugs)
rawhide
All Linux
medium Severity medium
: ---
: ---
Assigned To: Release Notes Tracker
http://fedoraproject.org/wiki/DocsPro...
:
Depends On:
Blocks: fc-relnotes-traqr
  Show dependency treegraph
 
Reported: 2005-10-04 16:38 EDT by Dan Mocsny
Modified: 2007-11-30 17:11 EST (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2007-02-10 10:07:25 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Dan Mocsny 2005-10-04 16:38:31 EDT
Version of release notes this bug refers to:

Fedora Core 4 final release

I found these items that could improve:

1. Errors

a. Should the word "uses" be "users"?

  http://fedora.redhat.com/docs/release-notes/fc4/#sn-new-in-fc
  1.1. New in Fedora Core 4
  Improved Security — SELinux is a security architecture that protects
  applications and uses [sic] through finely grained security controls.

If the author really does mean "uses", the sentence should answer the
question: uses of what? I.e., what is being used? And by whom or what?
I cannot tell from context whether the word should actually be "users".

b. "compliment" should be "complement":

  http://fedora.redhat.com/docs/release-notes/fc4/#id2502937
  6.1.1. Fedora Extras Repository

  Fedora Extras is part of the larger Fedora Project and is a
  volunteer-based community effort to create a repository of packages
  that compliment [sic] Fedora Core.

Reference:

  http://www.m-w.com/cgi-bin/dictionary?book=Dictionary&va=compliment
  Main Entry: 2 com·pli·ment
  Function: transitive verb
  1 : to pay a compliment to
  2 : to present with a token of esteem

  http://www.m-w.com/cgi-bin/dictionary?book=Dictionary&va=complement
  Main Entry: 2 com·ple·ment
  Pronunciation: -"ment
  Function: verb
  transitive senses
  1 : to be complementary to

  http://www.m-w.com/dictionary/complementary
  Main Entry: com·ple·men·ta·ry
  Pronunciation: "käm-pl&-'men-t(&-)rE
  Function: adjective
  2 : serving to fill out or complete
  3 : mutually supplying each other's lack

Clearly the correct verb is "complement."

c. "variables" should probably be "variable":

  http://fedora.redhat.com/docs/release-notes/fc4/#sn-nptl
  6.1.3. LinuxThreads versus NPTL

  You now need to also specify this variable in the environment:

  LD_LIBRARY_PATH=/lib{,64}/obsolete/linuxthreads

  This additional variables [sic] is required because the run/time
  libraries have been moved out of the way.

d. Missing "to":

  http://fedora.redhat.com/docs/release-notes/fc4/#sn-kernel

  These Instructions Refer [sic] The Currently-running Kernel!

2. Ambiguities

a. How to run sha1sum on a Fedora Core CD?

  http://fedora.redhat.com/docs/release-notes/fc4/#id2501928
  5.2. Anaconda Notes

    Use the sha1sum utility to verify discs before carrying out an
    installation. This test accurately identifies discs that are not
    valid or identical to the ISO image files.

I could not guess the correct command syntax to "use the sha1sum
utility to verify discs", even after I read the output of "man
sha1sum". The command:

  sha1sum /media/cdrom

immediately returns the error:

  sha1sum: /media/cdrom: Is a directory

This command:

  sha1sum -b /dev/hdc

causes the CD-ROM drive to light up for five minutes (it's an old
slow CD-ROM drive), and then the sha1sum command displays this 
error and exits:

  sha1sum: /dev/hdc: Input/output error

Readers who are new to Fedora Core may not know what "use the
sha1sum utility" means. The release notes should state the
exact command syntax. Readers who only have a computer running
Windows on which to burn the Fedora Core CD-ROMs may have
difficulty burning CD-ROMs that pass the linux mediacheck
command. The CDs I burned with Adaptec EZ-CD Creator fail the
mediacheck, and yet I was able to install Fedora Core and I
ended up with an apparently working system. I did check the
ISO files I downloaded with sha1sum as the installation instructions
say, but I don't know how to check the CDs I burned. mediacheck
says they fail, but they seem to work anyway.

3. Style Improvement

a. "For reporting" can shorten to: "To report". Shorter is better.

  http://fedora.redhat.com/docs/release-notes/fc4/#sn-intro

  For reporting errors or other requests about these release notes,
  file a bug report using this pre-filled bugzilla template:
Comment 1 Release Notes Tracker 2007-02-10 02:45:22 EST
These are good corrections, I'm sorry to say that we probably did not make most
of these changes; it appears this bug wasn't reviewed properly.  For the moment,
I'm going to block the tracker bug so we can review the content here in
comparison to the source.

If you are interested in contributing more directly, the release notes content
is written in the Wiki:

http://fedoraproject.org/wiki/Docs/Beats
Comment 2 Paul W. Frields 2007-02-10 10:07:25 EST
These bugs have all either been fixed or have obsolesced since FC4 release.  We
invite you to participate directly in the Release Notes process by joining the
Fedora Documentation Project!  Thanks for your feedback.

Note You need to log in before you can comment on or make changes to this bug.