wireless networking tutorial is available!

[Karsten Wade]

On Wed, 2004-04-14 at 08:16, Kenneth M. Benoit wrote:
> Hey Guys,
> 
> This is just a note to let you know that a wireless-networking-tutorial is avaliable.  
> 
> You can view the html at....
> http://www2.gvsu.edu/~simonjm
> 
> The tarball is available at...
> http://www2.gvsu.edu/~simonjm/wireless-tutorial-images.tgz
> 
> Please provide feedback...

Sorry I'm a little late (about 30 days) with replying.  Hope these
comments are of use.

This is a great tutorial.  Let's get this finalized and posted on 
http://fedora.redhat.com/docs/.

Some detailed comments, next time if you make XML available I'd be happy
to do these as patches.  This also gives us all a chance to validate the
quality of the source.

## http://www2.gvsu.edu/~simonjm/index.html

I think you can safely remove <holder>&FORMAL-RHI;</holder>, unless you
are offering joint copyright with Red Hat. :)

It might be worth it to work 'Fedora Core 1' into the title, perhaps as
a <subtitle>.  These are the entities I am using, and will be proposing 
to this group for common usage:

<!ENTITY FED "Fedora">  <!-- Generic root term -->
<!ENTITY FC "&FED; Core">  <!-- Generic main project name -->
<!ENTITY FCX "FC">  <!-- Short project name -->
<!ENTITY FP "&FED; Project">  <!-- Generic overall project name -->
<!ENTITY FDP "&FED; Documentation Project">  <!-- Generic docs project
name -->
<!ENTITY FDPX "&FED; Docs Project">  <!-- Short docs project name -->
<!ENTITY FCVER "1">  <!-- Current release version of main project -->
<!ENTITY TESTVER "test3"> <!-- Current test number of main project -->
<!ENTITY FCTESTVER "2 &TESTVER;">  <!-- Current test version of main
project  -->

With those, you could include <subtitle>&FC; &FCVER;</subtitle>.

## http://www2.gvsu.edu/~simonjm/assumptions-section.html

I like this page.  Good, clean format.  The footnote usage is a clever
way to separate the two information flows.

One spelling mistake, a word I have repeatedly misspelled so have
learned it by heart: 'privileges.'

##
http://www2.gvsu.edu/~simonjm/instructions-for-the-impatient-section.html

Might be worth including a method to obtain root 'privileges', such as
'sudo iwconfig ...' or just 'su'.

The Assumptions page says, "Root priveleges(sic) allow you to make
changes to the system you are working on. To set up wireless networking,
you will only need the password for the root user."  This doesn't hold
true for iwconfig.

I like the "impatient" v. "detailed" separation.  The "impatient"
section also serves to offer the user a path to higher knowledge via the
command line, without making that the focus of the tutorial.

## http://www2.gvsu.edu/~simonjm/detailed-procedures-section.html

Suggest in step 2, change to read:

"2. Select the device you wish to configure and click
<guibutton>Forward</guibutton>.The devices listed in the
<guilabel>Wireless card</guilabel> list box are devices ...snip...
beyond the scope of this tutorial.  After selecting your device, click
<guibutton>Forward</guibutton>."

Oh, wait.  I just discovered that <guilabel> and <guibutton> have the
same output from our stylesheet, so without your XML I don't know which
you are using.  I'll stop "fixing" this now, just a note that the
difference is important in the mark-up even if the output is the same.

"3. Select from the <guilabel>Mode</guilabel> drop-down list the mode
appropriate..."

I don't understand the sentence under the Managed bullet, "However, you
may have a(sic) Internet Service Provider that uses a wireless
Connecting to an accesspoint(sic)."  I can't suggest how to fix it
because I'm not sure what you are trying to say.

Tip:  when quoting text from the GUI or screen, use the exact wording,
syntax, and formatting.  E.g., in step 4, it should be, "Enter the
<guilabel>Network name SSID</guilabel> (Service Set IDentifier)."  This
not only ties your instructions back to the applet and the screenshots,
it keeps the reader from feeling confusion and doubt when the
documentation doesn't match what their eyes are seeing.

So, for step 6, "Next, select from <guilabel>Transmit rate</guilabel>. 
The values need to match the transmission rate..."

9. "...assigned an Internet Protocol (IP)..."
                 ^
# http://www2.gvsu.edu/~simonjm/Ending_Procedures.html

Suggest linking to an object with <xref> whenever it's mentioned in the
body of text, e.g. <figure>, <example>, etc.:

"After adding the new wireless card to your system successfully, you
will see the window in <xref linkend="name-of-figure-ID">:

Last suggestion is to replace the word 'surfing' in the final paragraph.
:)

hth - Karsten
-- 
Karsten Wade, Tech Writer
this .signature subject to random changes`
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41