some possible user guide edits

[Murray McAllister]

Hi,

I read through a little of the user guide on the weekend. I made a
list of some possible changes. Since I do not contribute, and most are
just nitpicks anyway, feel free to discard ;-)

The file is a bit of a mess sorry (no spell checking, no reread, and I
think I messed up the page numbers). Let me know if you have any
questions.

Thank you!

2.3. I Cannot Login: HELP!
* heading does not use sentence case like the previous headings. So:

I cannot log in: help!

?

6.2.3. Using GnomeBaker in Gnome
* Gnome -> GNOME

12.7. GNOME multimedia applications
12.7.1. CD/DVD Creator
12.8. GNOME multimedia applications in the repository
* can this all be in section 12.7?

page 88, 12.8. GNOME multimedia applications in the repository
First sentence, "These applications are not usually installed by
default but are in the Repository."
* should "are in the Repository" be "are in the repository"?

Last sentence, "You can install applications by either using the
PackageKit or on the command line by using Yum."
* should "Yum" be "yum" in this case, or is it talking about the
application, not the command?
* also, "using the PackageKit" or "using PackageKit"?

page 92, 12.10. Multimedia Programs in the Repository
* should the heading be, "Multimedia programs in the repository", to
keep consistent with other style used for previous headings?

12.10. Multimedia Programs in the Repository
The applications...
* should this be "The programs", or the heading changed to "Multimedia
applications"?

Second sentence, "To install these packages please, read [[User Guide
- Managing Software|the chapter on managing software]]"
* should be a link, no?

Heading 12.11. MP3 Players, 12.11.2. iPod Connectivity, and 12.12.
Further Information, should these be sentence case (for consistency)?
So:
MP3 play...
iPod conne...
Further info...

page 43, chapter "Accessing the Web"
* current form of first sentence:

Fedora uses Mozilla Firefox by default in Gnome and Konqueror in KDE
to access the World Wide Web (Web).

suggested form (or at least please change Gnome to GNOME, thanks!):

For Fedora, Mozilla Firefox is the default web browser when using
GNOME, and Konqueror is the default web browser when using KDE. These
browsers are used for accessing the World Wide Web (Web).

* should "World Wide Web" be replaced with "Internet", as the third
paragraph starts with "The Internet can also"?

* current form of the third sentence in the third paragraph:

If you wish to transfer files using email, then you should probably
read Chapter 9, Communications instead.

suggested form:

If you wish to transfer files using email, refer to Chapter 9, Comm...

page 43, section "8.1.1.1. Navigating the web"
* first paragraph, second sentence, "navigation bar across the top of
the Firefox screen". The third sentence of the third paragraph says
"menu from the top of the Firefox window". Should "Firefox screen" in
the first paragraph be replaced with "Firefox window"?

* current form of the first and second sentence of the third paragraph:

Like other web browsers, Firefox makes it possible to save a web page
for future reference by adding it to a list of bookmarks. Use the key
combination Ctrl+D to bookmark a page you are viewing.

suggested form (since the bookmark feature saves the address, not the
entire page like save as would do. right?):

Like other web browsers, Firefox makes it possible to save the address
of a web page for furture reference, by adding it to a list of
bookmarks. Use the key combintation Ctrl+D to bookmark the page you
are viewing.

page 44, first Note, "Use your favorite feed reader", last sentence,
"Another option is to use a desktop feed reader you have installed,
such as Liferea."
* is Liferea installed by default for GNOME, KDE, and Xfce users? If
not, how about the following?

Another option is to use a stand-alone, desktop feed reader, such as Liferea.

page 44, section "8.1.1.3. Extensions"
* first sentence of the second paragraph states, "To manage and
install extensions, plug-ins...". The note following this paragraph
uses "plugin" in the title. The Note body also uses "plugin". These
should all be "plug-in", no?

* second sentence of the second paragraph, "New extensions are found
by visiting the Firefox add-on site". The note following this
paragraph states:

All of these can be found at Mozilla's Firefox add-ons site

Can the version in the Note be changed to the version in the paragraph
(e.g., is it safe to make Mozilla (a trademark?) possessive?)

page 44 -> page 45
* 5 notes/warnings/info boxes in a row. Page 45 has 3 of them visible
on the screen. Such repetition of these make them quickly lose their
meaning, no?

Also, "8.2. Transferring files" section starts with a box. I am not
sure if these should be used as the first content.

page 45, "8.2. Transferring files" section, second sentence of first
paragraph, typo "On" instead of "One":

On of the most common methods

page 45, "8.2.1. Using FileZilla" section
*current form of the first sentence of the first paragraph:

FileZilla is an application that allows you to transfer files over FTP
using a simple graphical interface.

suggested form (do you transfer files over a protocol, or do you
transfer them over a network?):

FileZilla, an application with a simple, graphical interface, allows
you to use the FTP protocol to transfer files over a network (and the
Internet).

* last sentence of the first paragraph, "This way, you can browse to a
file on a remote server and drag- and-drop it to a folder on your
local host.". Change "your local host" to "your local machine", to be
consistent with the other terms in this paragraph?

* second sentence of the second paragraph, "PackageKit or on the
command line using Yum". Should "Yum" be "yum", or is it talking about
the application?

* "FTP with web browsers" note, first sentence uses "don't". Should
this be, "do not" (Do "'t" make it hard for translation?)

page 45, 46, section "8.2.1.1. Connecting to a server"
* current form of the second paragraph:

When the Site Manager dialog is open, click the New Site button. The
first thing FileZilla will want to know is the name that you want to
use to refer to this server. There will be a text entry box under My
Sites on the left side of the dialog. Here, type whatever name you
want to use to refer to the new server. This name doesn't have any
technical implications; choose something convenient for you.

suggested form:

Click the New Site button when the Site Manager dialog is open. In the
text entry box under My Sites (on the left side of the dialog), enter
the name you want to use to refer to this server. This name does not
have any technical implications; choose something convenient for you.

page 46
* Host section, "Otherwise, you'll need to type in the IP address",
"The server you are connecting to should provide you with this
information.". It is my limited understanding that you would need the
IP address before attempting to connect, so I cannot parse how one
discovers the IP address if you need to be "connecting" to it first.

Maybe just change to say use the URL, if you do not have this, use IP
address...and cut off the "The server you are connecting" to sentence?

* Port, current form:
You only need to fill in a value for this field if the server does not
use the default (port 21 for FTP, port 22 for SFTP).

"does not use the default", the default what? How about:

Only enter a value in this field if the server you want to connect to
is not using the default ports (port 21 for FTP, port 22 for SFTP).

* Servertype, current form:

Here, you can choose FTP, SFTP, FTPS, or FTPES. Only FTP and SFTP will
be discussed here.

Discussed where? How about:

Choose either FTP, SFTP, FTPS, or FTPES. Note that this section only
discusses FTP and SFTP.

* Logontype, current form:

This field allows you to choose how you will authenticate with the
server. This information should be provided by the server you are
trying to connect to.

"This information should be..." does this mean, do not fill in the
field, when you press connect (or whatever the button is called :) )
it will be filled in for you?

* User, Password, Account, current form:

These fields will only be active if you user certain Logontypes. If
they are active, you should use them for your username, password, and
account on the remote server.

How about the following?

These fields are only active when certain Logontypes are used. If
active, use them for your ...

* first two paragraphs after the above list use "Site Manager" in
normal text, but it is bold on the previous pages. Is it ommitted
here, since it would make too much bold?

* last paragraph, current form:

To connect to a server later on that you have already added to Site
Manager, simply open the Site Manager, click on the server you want to
connect to, and click Connect.

suggested form:

To connect to servers already added to Site Manager, open Site Manager
and click the server you want to connect to, and then click Connect.

page 46, section "8.2.1.2. Transferring files"
* first paragraph:

If you connect to a server successfully, you should see some status
messages appear in the top pane indicating that you have connected to
the remote server.

Should I see them, I will most definitely see them every time (part of
FTP protocol??)? How about something a bit shorter?

Once connected successfully, status messages (in most cases) appear in
the top pane, indicating the successful connection.

* second paragraph:

To transfer a file, simply drag-and-drop it from one file browser into
the folder of the other file browser.

I have not used this application before, but do you have two instances
of it open at the same time, or is this describing that 1 instance of
the application will have two windows / browsers (one on the left
local, right hand side remote?)


8.2.2. FTP on the command line
To use the ftp program, type ftp at a console prompt

* are "command line" and "console prompt" the same? Would it be easier
(for a user guide), to just use one term or the other?

* I would remove the following sentence: "You should be put into an
FTP shell that looks like this:"

* current form of the second paragraph:

To get a list of commands, type help. To get a simple description of
any command, type help command. This guide will only cover a fraction
of these commands; read about the rest in the ftp man page.

suggested form:

Type help to get a list of commands, and help command for a simple
description of that command. This guide does not cover all commands.
Refer to the ftp manual page for further details.

8.2.2.1. Connecting to an FTP server
To log in to an ftp server, use the open command.

* how about "Use the open command to connect to an FTP server", or at
least ftp server -> FTP server?

* second sentence, current form:

The syntax is open ftp.server.com port Where ftp.server.com is the FTP
server you wish to connect to.

missing full stop ("Where" is used twice like this)? Suggested form:

The syntax for this is open ftp... where ftp.server.com is the FTP
server you wish to connect to.

* third sentence, current form:

It is not necessary to specify a port with this command unless you are
connecting to a non-default port.

suggested form:

Only specifiy a port if you are connecting to a server that uses a
non-default port for FTP (the default is 21).

Remove "The default port for FTP is port 21" based on the above rewrite.

* last sentence:

To do this, use the syntax ftp ftp.server.com portftp.server.com port
Where the port option is, again, optional.

Missing space, and I don't think I need to type ftp.server twice, or
provide two ports. As well, how about "The port option is optional"?

page 47, "8.2.2.2. Managing files" section

* how about changing the heading to "downloading and sending files"?

* first sentence, "Often, FTP is used to retrieve a file from a public
server.". Is this what is called a dangling modifier? How about:

FTP is often used to retrieve files from public servers.

* rest of the paragraph, current form:

You can obtain this file from the server by using the get file
command, where file is the name or path of the file you want to
retrieve. To view all the files in the directory you have connected
to, you can use the ls command. You can also use pwd to determine
which directory you are currently in, and then cd to change your
directory.

suggested form:

Use the get file command to obtain a file from the server, where file
is the name of or path to the file you want to retrive. Use the pwd
command to determine which directory you are in, and the ls command to
view all files in this directory. Use the cd command to change
directories.

* second paragraph, current form:

To send a file to the server, type putfile, where file is the name or
path of the file you wish to send. To view all the files in your local
directory (not the remote FTP server), type lcd. You can also type lcd
directory to change to a new directory on your local machine.

suggested form:

Use the put file command to send a file to the server, where file is
the name of or path to the file you want to send. Use the lcd command
to view all files in your local directory (not the remote FTP server).
Use the lcd /* is this a typo? */ command to change to a different
directory on your local machine.

page 47, "8.2.2.3. SFTP on the command line" section.
* some notes:
- "Secure FTP, or SFTP", should this be "Secure FTP (SFTP)?

- "It connects over to the remote server through a secure socket
layer, like SSH", connects over what? Why not just "connects to a
remote server"?
Does it use a secure socket layer like ssh, or does it actually use
SSH? The sftp man page on Mac OS X (sorry :P) says "sftp is an
interactive file transfer program, similar to ftp(1), which performs
all operations over an encrypted ssh(1) transport.", and ssh(1), "ssh
-- OpenSSH SSH client (remote login program)".

- "Use the command sftp to start the client. The syntax is nearly
identical to the syntax for FTP", since it is talking about commands
and syntax, how about "The syntax is similar to that of ftp"?

page 47, "8.2.2.4. Secure copy (SCP)" section
* first paragraph, current form:

Another option for transferring files between two computer with SSH is
using the command scp. This attempts to use the same syntax as the
tradition copy command (cp), but differs in that you can specify
remote servers. For example, to send a file to a remote server, type

suggested form (or at least change "two computer" to "two computers",
and "tradition copy command" to "traditional"?):

The scp command is another option for transferring files between two
computers via SSH. scp attempts to use the same syntax as the
traditional copy command (cp), but differs in that you can specify
remote servers. The following is an example of using scp to send a
local file to a remote computer:

* last sentence:

In every case that you access a remote server, you will be prompted
for your credentials (such as a username and password).

I am not an ssh expert, but is this always the case (e.g., if you run
ssh-add, enter passphrase once, servers support keys instead of using
password, etc)?


page 39, Chapter 7, "Connecting to the Internet"
* first paragraph:

Fedora includes a graphical tool to help configure various connections
and network interfaces. KDE is included by default and allows easy
management of configured connections.

"KDE is included...". Is this a spelling mistake, or am I not reading
it correctly?

* 7.1. GNOME
7.2. KDE

Why are there subsections for two-sentence paragraphs? How about using
formalpara instead, or perhaps better, no tags?


* 7.3. Configuring PPPoE section, first paragraph

PPPoE connections are primarily used for xDSL connections. PPPoE
stands for Point-to-Point Protocol over Ethernet.

How about use only one sentence?

Point-to-Point over Ethernet (PPPoE) connections are primarily used
for xDSL connections.

* second paragraph:

In the main screen, click the New Button and then choose XDSL
Configuration from the left hand column, clicking the Next button to
proceed.

Why is this sentence on its own? In the main screen of what?
For GNOME and KDE, is the network config tool the same, i.e., is this
talking about system-config-network?

* third paragraph:

In the following screen, enter the name of the xDSL provider

Following screen of what? How about making this whole section an itemized list?

In the following screen, enter the name of the xDSL provider, and the
username and password belonging to this account.

...this account. What account? How about "username and password for
your xDSL account"?

* fourth paragraph:

To configure this network connection to start when the system boots,
click the appropriate entry in the main dialog, and then click the
Edit button.

New paragraph. Which network connection is the "this network connection"?

page 39, "7.4. DHCP connection" section.
* first content is a Note. Is a note really needed here?

* first sentence, first paragraph:

DHCP connections are common when using cable modems,

I am not an networking expect, but I don't know about "DHCP
connections". This section also doesn't explain what DHCP actually
is...how about:

Connections configured to use DHCP receive (most?) of their network
settings automatically, without the need for manual configuration.

* second paragraph:

To enable DHCP for a particular network interface,

But it is enabled by default, no? How about how to turn it off (and
note in that paragraph how to turn it back on)?

*, "7.5. Static IP address", second sentence, first paragraph:

"Next ensure that Statically IP addresses is marked". If that is what
the dialog really says, someone should make a bug ;)

* "To configure a network interface for a static IP address," -> I
think you configure the interface with a static IP address, no? How
about:

To configure a static IP address for a network interface

* last paragraph:

For a static IP address, it is also necessary to fill in the details
under the DNS tab of the main interface.

What details? How about:

When configuring an interface with a static IP address, it is also
required to fill in Domain Name System (DNS) details under the DNS
tab. Without this information, you will not be able to .. blah... look
up .. navigate to web pages, etc.

page 40, "7.6. NetworkManager" section
* first paragraph, current form:

NetworkManager is not enabled by default in Fedora, it is installed by
default however. Enabling NetworkManager is a simple process of going
to System > Administration > Services and checking Network Manager and
Network Manager Dispatcher.

suggested form:

NetworkManager is not enabled by default in Fedora, but it is
installed by default. To enable NetworkManager, navigate to System ->
blah, and check (select some tick box..I am not sure what check is
here, sorry)

* current form of the note:

Make sure to save the modifications otherwise the changes will not be
written to file. To start them straight away you will need to
highlight Network Manager and Network Manager Dispatcher and click the
Start button.

suggested form:

Make sure you save the modifications otherwise the changes will be
lost. To start Network Manager and Network Manager Dispatcher,
highlight them and click the Start button.

* second paragraph:

NetworkManager simplifies the process of connecting your laptop or
desktop to the network. When you have enabled the programs you should
see the nm-applet icon.

does it appear after I enable them, or does it only appear when it is running?

* third paragraph:

When it has been enabled you can right click on the icon and enable
wireless or wired networks. Enabling both does not affect how
NetworkManager operates.

Should be part of the second paragraph, no?

* fourth paragraph:

If you have a wireless network and it is supported by Fedora left
clicking on the icon and selecting Connect to other network and
putting the details of your connection will cause NetworkManager to
use that information to connect to the network.

- I think Fedora can use all wireless network standards, but it will
not support wireless *cards*, yes?
- Can this sentence be broken up into two, or some commas added?

page 40, 7.7. Wireless section, first paragraph:

Fedora includes some wireless firmware and methods to install
closed-source firmware. NetworkManager automatically functions with
the drivers that you installed in Fedora.

What is the difference between firmware and drivers, and what is firmware?

* last paragraph/the Note in this section:

A current bug with some of the firmware is that the wireless light is
not enabled, this does not mean the wireless card is turned off

- missing full stop
- what bug is that so I can add myself to Cc and know when it is
fixed? (<ulink url="blah.bugzilla/1234">a bug</ulink>)?
- how about "is not enabled. This does not..."

page 41, 7.8. Remote desktop
* Gnome -> GNOME
* second paragraph:

Enabling 'Desktop Sharing is as simple as ticking the Allow other
users to view your desktop.

What is "'Desktop" for (typo, ', ?)

How about:

Tick the blah to enable Desktop Sharing.

This section seems to be "Chapter 17, Sharing your desktop", but does
not link to it.