Course Title: Technical Communications in the UNIX Environment: Understanding UNIX Documentation and Technical Publication Tasks (X447.1)
EDP 321182
Dates: 16 September 1999 - 14 October 1999
Instructional Hours: Five Thursday evenings 6:30 pm - 9:30 pm
Location: U.C. Extension Downtown Center, San Francisco;
Room 803, 425 Market St., 8th floor (enter on Fremont Street).
[2 blocks from BART Embarcadero Station]
Instructors: Thomas Albert and Bruce Overby

Thomas Albert, Ph.D., Staff Technical Writer at Rational Software, creates administrator guides and online Help for UNIX and Windows NT power users. His 8 years of experience include producing technical publications for Oracle, Kodak, and Ericsson with all the major operating systems, including UNIX. He holds a Certificate in Computer Information Systems from UC Berkeley Extension, and was Erie Community College Assistant Professor for Written Composition.
Web site with syllabus: www.WORDesign.com.
E-mail: talbert@WORDesign.com.

Bruce Overby, M.A. is the Documentation Manager of Ariba Technologies, and formerly Manager of Technical Publications and Information Design at Sun Microsystems. He has spent the past 10 years of his career producing documentation for HP-UX, Sun Solaris, and other Unix platforms. E-mail: deucer@well.com.

Target Audience: Technical communicators and prospective technical communicators wanting a gentle "bridge" course to introduce the world of UNIX from the perspective of a technical communicator working with engineers who use UNIX.
Brief Description: Technical communicators often work in a UNIX environment. This course bridges the communication gap between the (prospective) technical writer and UNIX power user. This course enables writers to quickly begin working in any UNIX environment. Students learn the concepts and vocabulary they need to communicate with engineers using UNIX, as well as hands-on skills to access engineering specifications, navigate the file system, edit text files, and archive documents. Emphasis on "man page" skills empower students to begin solving problems on their own. Students perform hands-on homework assignments using Sun Solaris 2.x, the most common UNIX environment for technical publication departments. Students also learn what LINUX is and how to run this non-proprietary system on their personal computer. Students completing the course will have a portfolio piece demonstrating their UNIX skills: an HTML page of their edits to UNIX online documentation.

Prerequisite: Ability to use common software applications   (PC or Mac) and access to the Internet.

Educational Objectives: Students learn
  • what an operating system is, why UNIX is the platform of choice for many engineers, and what some of the various "flavors" of UNIX are
  • what UNIX skills a technical communicator needs versus system administrator issues
  • basic UNIX utilities for securing and managing programs and files
  • how to archive document files, and how to retrieve them from an archive and uncompress them
  • how to use UNIX online documentation (the man pages), and UNIX in a Nutshell, to solve problems without asking engineers for assistance
  • how to edit a file using vi (or another text editor)
  • how to use ftp to post a simple web page with links to available documents
  • how to apply Solaris 7 skills to LINUX running on a personal computer
Required Texts: An reader-friendly tutorial book:
SAMS Teach Yourself UNIX in 24 Hours, Second Edition
By Taylor, Dave / Armstrong, James C.
Softcover; 529 Pages
Published by Macmillan Computer Publishing
Date Published: 1998
ISBN: 0672314800
List Price: $19.99
The classic reference book:
UNIX in a Nutshell : A Desktop Quick Reference for System V and Solaris 2.0
By Gilly, Daniel
Softcover; 400 Pages
Published by O'Reilly & Associates, Inc.
Date Published: 06/1992
ISBN: 1565920015
Online Price: $15.95
Recommended, depending on your preferences: Very user-friendly guide to specific tasks:
UNIX Visual Quickstart Guide
By Ray, Deborah S. / Ray, Eric J.
Softcover; 300 Pages
Published by Addison Wesley
Date Published: 11/1998
ISBN: 0201353954
List Price: $17.99
For those of us who started with MS-DOS:
UNIX for DOS Users
By Arick, Martin R.
Softcover; 256 Pages
Published by John Wiley & Sons
Date Published: 06/1995
ISBN: 0471049883
Online Price: $27.95
Beyond the scope of this introduction, but a highly regarded book:
UNIX Power Tools, Second Edition
By O'Reilly, Tim / Peek, Jerry / Loukides, Mike
Softcover; 1073 Pages
Published by O'Reilly & Associates Inc.
Date Published: 06/1997
ISBN: 1565922603
List Price: $59.95
Beautifully clear book with screenshots and diagrams shows you "The NT Way" and "The Solaris Way" for general operating system philosophy and specific tasks, such as sharing files and printers, and email/web administration.
Solaris Guide for Windows NT Administrators
By Tom Bialaski
Softcover; 140 Pages
Published by Sun Microsystems Press
Date Published: 1999
ISBN: 0130258547
List Price: $28
Teaching Aids:
  • Blackboard or whiteboard
  • Overhead for transparencies
  • LCD projector for live demonstrations
  • Telephone jack for dialup connection to the lmi.net shell server with class files
  • Class syllabus and lecture/lab notes posted at course website
Teaching Methods:
  • Lecture
  • Class discussions
  • Live demonstrations using one or both of the following:
    • dialup telnet sessions to the lmi.net shell server with class files
    • MKS Toolkit (trial version) to emulate UNIX on the students' personal computers (for homework)
  • Review of weekly take-home quiz
  • Homework: exercises with UNIX commands
  • Course Project: a portfolio piece demonstrating mastery of UNIX tasks a technical communicator often performs
Course Project:
  • Portfolio Piece demonstrating student's UNIX skills in using telnet, ftp, and vi to edit UNIX man pages on ten commands technical writers use, and upload the document to a UNIX server for use as a web page.
Grading Criteria Homework 40%; Take-Home Quizzes 20%; Final Project 40%
Instructional Facility Needs:
  • Telephone jack in classroom to establish a dialup connection for demonstrations using a telnet session to the lmi.net shell server with class files
  • One or both of the following:
    • A five week account with write privileges to a  third-pary UNIX server (the lmi.net shell server with class files)
    • MKS Toolkit (trial version) to emulate UNIX on the students' personal computers
Special Considerations:
  • Some students have telnet access already
  • Students can obtain a free, one-month trial account at CompuServe, which supports telnet
  • Macintosh users can buy MachTen ($250), a full Unix environment running on an Apple computer. http://www.tenon.com/products/machten/
  • Another option: students can download the trial version of MKS Toolkit ($400), which enables their personal computer to emulate a Unix machine
    http://www.mks.com/

Content

Session 1
16 September:
Introducing UNIX
Why are hands-on UNIX skills valuable to a technical communicator?
  • Perform job responsibilities independently
  • Enhance communication with engineers through shared experience and a common vocabulary
  • Demonstrate technical aptitude to engineers and managers
  • Post a web page without needing special tools

End-user vs administrator tasks

Historical chronology


What is UNIX?

  • What is an operating system?
    • kernel
    • user interface
      • shell
      • graphical user interface computing environment
  • UNIX console compared with DOS prompt
  • Solaris CDE compared with Windows NT/Windows 95
  • Why is UNIX the dominant operating system for Internet servers?
  • Security
  • Stability
  • True Multithreaded
  • Relation of UNIX to C and Perl
  • UNIX command line versus UNIX graphical user interfaces (Motif, XWindows, Solaris CDE)
  • What are the "flavors" of UNIX?
    • Sun Solaris 2.6 the most common
    • LINUX can run on your PC
    • Other flavors
  • Basic vocabulary: man page, text editor, login versus rlogin, root versus user, terminal emulation, telnet, ftp, dumb terminal, console, prompt, kernel, shell, script, daemon, background process, killing a runaway process, vi, regular expressions, pipe, permissions

Demonstration

  • ftp and telnet to the remote server
  • DOS commands and their UNIX equivalents using a DOS prompt and a UNIX shell simultaneously (copy/cp, dir/ls, cd/pwd, rename/mv, type/cat, del/rm, rd/rmdir)
  • Quick tour of the Solaris CDE and a LINUX GUI
Homework:
  • Obtain one or both of the following:
    • telnet access (for example, a trial account on CompuServe)
    • MKS Toolkit (trial version) to emulate UNIX on the students' personal computers
  • Take-home quiz about lecture material
  • Write a short UNIX glossary using terms discussed in class
Session 2
23 September:
Basic UNIX Hands-On
Guest Lecture and Unix Demonstration by Daniel Gilly, author of Unix in a Nutshell
  • introduction to the most common Unix reference
  • practical use of the reference while using Unix

(6:30 - 8 pm)


Navigating the file system using relative and absolute path names; using pwd and "cd .."
Exercise:
Using the ls command with common flags (-l, -F, -a, -s)

using redirection and pipes

using aliases and setting the shell environment

printing filing, viewing the print queue, removing a job from the queue

stopping a print job

getting word count with wc

Unix counterpart to Winzip: tar, untar, and compress files

Demonstration:

  • Dial up to a remote UNIX shell and archive
    (tar and compress) a set of FrameMaker documents
  • Retrieve and untar a set of HTML files

how to create, rename, and delete files and directories

Demonstration:

  • redirection and pipes
  • Using rm with the -i flag to avoid unwanted recursive deletions
  • Using tail | more to search within a mailbox
  • Using history to recall commands
  • Correcting commands with carets
  • Using the script command to do class homework

 

  • looking at the graphical shell
Homework:
  • Use telnet account (or MKS Toolkit) to access the class files and copy them into the subdirectory with the student's name
  • use script command to record telnet session
  • rename certain files
  • Create a directory and a subdirectory, then delete the subdirectory
  • Create and use an archive directory
  • Take-home quiz about lecture material
Session 3
30 September:
Intermediate UNIX Hands-On (1)
Cross-Platform Information by Sam Coniglio
  • brief history of Unix
  • comparison of Unix, Windows, and Mac
  • visit key Unix web sites

Setting permissions on files using chmod

Demonstration

  • Post a WinHelp system on the remote server and set the group permission to read-only

vi editing and Solaris text editor
Demonstration

  • Edit an existing HTML file on the remote UNIX server
  • Make two links to the "Technical Communications Department Homepage",
    one relative and one absolute

understanding the shell environment
Demonstration

  • using diff to compare two text files
Homework:
  • Use telnet account (or MKS Toolkit) to create a directory called "permissions"
  • Set permissions on files
  • Create and use an archive directory
  • Copy sample html page into a personal subdirectory on the server, then use vi to make 10 simple edits
  • Take-home quiz about lecture material
Session 4:
7 October
Intermediate UNIX Hands-On (2)
What is scripting? (Lecture by Bruce Overby)

"Scripting and Linux: Two Areas for Technical Communicators", A Guest Lecture by Paul Lane, technical writer at Oracle Corporation

  • examples of tech pubs scripts
  • the GIMP vs PhotoShop
  • bsh - the born-again shell
  • StarOffice: Sun's answer to Microsoft Office
  • Linux GUIs, games, and screensavers

mail tools: how to email your document to a developer using the mail –s and file redirection

how to use the file command to learn about types of files

How to use man pages (UNIX command-level online Help)

  • how to access man pages
  • how to grep man pages
  • how to interpret man pages
  • info to look for, and what to skip over

Demonstration

  • Use man pages to learn about printing, file ownership, and deleting files
  • Apply commands already learned to edit a copy of selected man pages
  • Use vi to convert a man page to an HTML file
  • Edit the HTML in real-time using telnet
  • Post the man page on the server
Homework PROJECT:
Use man pages to view options for 10 commands

Use vi to edit the 10 topics

Use script to capture output

Post the edited topics and output in a text file or to a personal HTML file on the server (or the equivalent using MKS Toolkit)

Session 5
14 October:
Review and Moving Forward on Your Own
Review of skills learned in previous sessions.

Demonstration

  • Review of key commands and switches
  • Building and running a simple script

How to further explore the world of UNIX:

  • Common UNIX HTML editors and help systems (HyperHelp,Web help, HTML Help
  • shell scripting, including scripting for FrameMaker on UNIX
  • Running LINUX on your PC
  • Unix and the Web
    • Common Gateway Interface (CGI)
    • Perl
    • XML

Project due

Authored by Thomas Albert and Bruce Overby on 3/31/1999; updated on 9/12/99
Copyright 1999, Regents of the University of California. All rights reserved.