Software documentation is a very hot subject. It continues to be
debated in all sorts of forums from CompuServe to user groups. Unless
the product is very intuitive, improperly documented software can be
almost worthless to use. Even if intuitive to use, many of the
functions lay hidden unless you have decent documentation.
Unfortunately for many, UNIX is not very intuitive. Therefore, good
documentation is essential to be able to use SCO UNIX to its fullest
Despite what many customers want to believe, SCO provides good
documentation. Well over half of all the calls to support can be
avoided by following the step-by-step procedures in the appropriate
section or sections in the manual. A large part of the remainder can
be avoided by not just following the steps, but understanding what is
being done and not just blindly following instructions.
Unfortunately, few administrators and very few users take the time to
read the manuals. This is not good for two important reasons. The
first is obviously the wasted time spent calling support for help on
things in the manual. The second is that you miss many of the
powerful features of the various programs. When you call to support,
you usually get a quick and simple answer. Tech support does not have
the time to train you how to use a particular program. Two weeks
later when you try to do something else with the same program, you're
on the phone again.
The biggest problem is that people see the stack of manuals that come
with a SCO UNIX system and are immediately intimidated. They would
rather spend the money to have support explain things rather than
spend time "wading" through all documentation. Some
customers do that and they pay a price. Most companies cannot afford
the thousands of dollars needed to get that kind of service.
The nice thing is that you don't have to. You neither have to wade
through the manuals nor spend the money to have support hold your
hand. The SCO manuals are like most books, they have a table of
contents, chapters that are logically grouped and at the end of
almost every manual is an index. In SCO OpenServer the manuals are on
line. This makes searching that much easier. In fact, you can search
every manual at once, if you like. You can even bounce between
difference places, using what are called "hypertext links."
Since knowing where to look is the biggest problem, that's the issue
we are going to address. I don't need to teach you how to read, or
understand a table of contents of how to interpret an index entry.
However, by making you more familiar with how the documentation is
laid out and where to look, you have a much better chance of finding
out the answers on your own.
There is no law that says to list a directory the command that you
must use is ls or
the way to add a user has to be added through the sysadmsh
or SCOAdmin. These are merely conventions that SCO has adopted. If
you are new to this environment, then many of the commands and
utilities seem very obscure to you. In order to be able to fully
utilize them, you need to know what they do. Often, the reverse is
true as well. The user (or administrator) knows there is a tool on
the system to do a certain, but doesn't know where it is.
This is where to documentation comes in. By looking at the
appropriate manual, you can quickly find what you are looking for. As
those of us who have been in the business for a while know, this is
easier said than done. SCO Documentation provides a wealth of
information. Almost any task that you need to get accomplished is
possible through reading the documentation. Often times,
documentation is not effectively used because the user or
administrator isn't sure where the information he or she wants
There are two major groups of documentation in SCO systems. The first
group is the "guides." These include the System
Administrator's Guide and User's Guide, which give step-by-step,
often very detailed instructions on procedures and activities on the
system. In the table of contents, each section heading is listed
along with its page number. A quick glance through the table of
contents can quickly point you to the right place. If that doesn't
work, there is an extensive index.
The User's Guide is user oriented, although a beginning administrator
would find of the information here to be very useful. The User's
Guide provides explanations of the various shells, file manipulation
programs such vi, sed and
awk. There are also
chapters on communication with other users with mail or other sites
For the administrator, there is a System Administrator's
Guide. Although it contains many of the same subjects, such as mail
and UUCP, these are from the administrative perspective. They
describe how to set-up and configure these programs and services. In
most cases, they provide step-by-step instructions for basic
installation and configuration. If that is not sufficient, there is
enough supplemental information for you to understand how things are
configured and interact to enable you to configure your system far
beyond the basics.
In addition and supplemental to the guides are the "references."
These include the System Administrator's Reference and the User's
Reference. Since these are simply descriptions of various commands
and utilities, often limited to a few pages, they are commonly
referred to as manual pages or man-pages for short. In many places,
including this book, you are encouraged to read the man-page for a
particular command, this is what we are talking about.
Unfortunately, the break down of commands listed in the man-pages is
not a clear cut as what is described in the Administrator's or User's
Guide. Often commands that serve administrative functions are listed
in the User's Reference or commands that users need is listed in the
This nice thing is that you usually don't have to know whether a
particular command is considered an admin command or a user command.
The system will tell you. Unless they have been removed or
intentionally not installed, man-pages exist on-line on your system.
They are part of the base installation and must either be explicitly
removed or intentionally not installed.
Built into the system is a command to read these man-pages: man.
By typing man <command>
you can find out many details about the command <command>.
There are several different options to man
that you can use to find out about by typing man
man, which will bring up the man
man-page. (or the man-page for man)
Often times there are entries in multiple sections. For example, in
the C section (where the commands are found) there is an lp
entry that explains are the various options to the lp
command. Additional, there is an lp
man-page in the HW (hardware) section that describes the various
parallel port possibilities. There is a man-page for tar
in the C section that talks about how to use the tar
command. In the F (file format) section, there is a man-page for tar
that describes the format of a tar
archive. At the front of both the User's Reference and
Administrator's Reference is an alphabetical list of all the commands
found in that book, along with a brief description of their function.
With OpenServer things are even different still. The only document
that is delivered standard is the SCO OpenServer Handbook. This is
comparable to the Release Notes and Installation Guide in previous
releases. If you want hard copies of the other doc you need to order
it. Keep in mind that all the documentation is already on-line.
Should you have Open Desktop installed or one of the extension
products, there are additional man-page for these products. If the
SCO Development System is installed, there are also several different
man-page categories available. Also, SCO ODT comes with additional
documentation such as the Graphical Environment Administrator's Guide
which contains information about customizing and administering the
graphical portion of ODT.
You will see very often in SCO Documentation when referring to a
particular command the name followed by one of the above letters in
parenthesis, such as ls(C). This
indicates that the ls
command can be found in the C section of the man-pages. By including
the section, you can more quickly find what you are looking for. Here
I will be making reference to files usually as examples. I will not
be adhering to that practice here. I will only say what section they
are in when I explicitly point you toward the man-page.
One very useful aspect of the man-pages is their reference to other
man-pages. At the bottom of many of the man-pages is a "See
Also" section. This points to man-pages that are related to this
one in some way. The reference might be to a command with similar
functionality, such as the rm
(remove) command has a reference to the rmdir
(remove directory) command. In other cases, the reference is to the
same heading in a different section, such as the
tar(C) man-pages refers you to the tar(F)
The references and guides that I talked about are not all there is to
SCO documentation. There are several other books that are supplied
with your product that contain different pieces of information. Some
of it can only be found in these books, while other pieces are
overviews and reviews of what appears elsewhere.
One common piece of documentation that is overlooked is the
Release Notes. The people that most often overlook the Release Notes
are those that have either been with SCO for some time or are
familiar with other UNIX dialects. Their attitude is that they "know
it all" or at least they know everything of importance and the
manuals cannot tell them anything new. This is not an exaggeration.
On many occasions I received calls from customers saying that they
"know how to do an SCO install." When they run into
problems, they call support only to find the solution in the release
Of all the books that can prove them wrong, the Release Notes is the
most significant. One of the key things that the Release Notes talks
about it difference between previous releases and the current one.
(Get it? They are notes about this release.)
After about twenty, I lost track of all the customers who called in
saying that there was a bug in the new version (SCO UNIX 3.2. version
4.0 and later) in that it didn't recognize their parallel or serial
port. In that the freshly installed or upgraded system did not
recognize these ports, they were 100% accurate. Where they were off
target was in the fact that it wasn't a bug. The release notes
clearly state that this is the case.
The reason that these drivers are intentionally left out is an issue
of space. With the release of SCO UNIX 3.2. version 4.0, there was a
substantial increase in the number of devices that it supported. Many
of them, such as SCSI host adapters, needed to be recognized during
the installation. To be able to do this they needed to be included in
the kernel on the installation disks. As a result, the kernel became
too large to fit on a floppy, so something had to go. What else make
sense other than something that is not absolutely needed during
installation such as serial or parallel ports?
In the Release Notes there is a list of all the documentation that
comes with the product. Here the Release Notes are described as
"crucial information for Open Desktop installation and
configuration." In many cases this is true. For example, if you
have only SCSI hard disks in your system you must tell the system
CMOS that there are no hard disks. If you don't, the hardware
will be looking for an IDE or ESDI hard disk and you'll never be able
to install. (This is crucial because if you don't do it right,
you can't boot.)
Another piece of documentation that is ignored and contains a wealth
of information is the Installation and Update Guide or the SCO
OpenServer Handbook. Again, the attitude is that this can't tell them
anything new. This is more likely to be true for someone who has been
working with SCO for a long time. However, if this is the first time
you are working with a particular release, there will definitely be
something here that's new.
This book is especially important to people who are new to SCO.
Countless customers will call in saying that after installation, they
are missing half of their harddisk. I have even dealt with people on
CompuServe with this same problem. Within a minute on the phone or by
reading the CompuServe message, I know that, no, the space is not
missing, they just didn't read the Installation and Update Guide. If
they had, they would have known that the "missing" hard
disk space is now part of a /u you filesystem and you have to tell
the system to go look at it.
If the customer does take up support on this offer (or they already
have a support contract) they then get to talk to support analyst.
When they are told that this is clearly documented the reaction is
often that they don't have time to read all the manuals. Well,
they aren't expected to, just the one relevant to the task at hand:
installation. The ironic part is that they have the time to call up
support and wait to talk to a support engineer, but don't have the
time to look for things in the manual.
Accompanying the Release Notes and Installation Guide is the Hardware
Configuration Guide. This gives a lot of hardware specific
information that can help during installation. In addition, this is a
very useful piece of documentation later when you decided to add
hardware to an existing system. Information about supported hardware
is also available from SCO Sales before you buy your system.
Once the system is installed, a good place to start is the Tutorial.
If you are new to SCO, or UNIX in general, this gives a quick
overview of the system. Even if you are an experienced SCO user, you
might learn a few tricks.
The documentation provided in SCO OpenServer took a giant leap
forward. Unless you specifically request hardcopy versions, then the
majority of SCO documentation only comes in its on-line version. At
first, I was bothered by this, as I like having the doc in front of
me. However, the only documentation that you really need to
have in hardcopy format is the release notes and installation guide,
and that's what you get.
fundamental structure of scohelp
is the same as the MOSAIC interface developed by the National
Center for Supercomputing Applications (NCSA) that many people use
for their World Wide Web browser. As with the WWW browser, documents,
images and other items are connected via "hypertext" links.
Because if this similar and the use of the http daemon, scohelp
can also provide file across the network.
Each of the hundreds of files composing the SCO Documentation
Library is conceptually the same as pages and go to form what are
referred to as "virtual" books. These books are what we
normally think of as documentation, such as the Administrator's
The files themselves are written in the hypertext markup language
(HTML), which can be used to link not only text but graphics and even
photographic images to documents. In some cases the document may
contain a reference to a particular image, which appears
automatically on the screen with that page is displayed. In other
cases, you click on a hypertext link, which causes scohelp
(or Mosaic) to go get and then display the image.
Hypertext links do not have to point to images. They can also point
to other documents, as well. Using this technique you can move
between different areas of the documentation, reviewing related
topics and then returning to your starting point. Because the
documentation is composed of individual files that are connected via
these hypertext links, changes can be made to individual pages
without having to redo the entire doc. When updates or patches are
installed, new or corrected pages can be installed into the SCO
Documentation library without anyone noticing. Because of the way the
links are defined, someone could be currently using scohelp
and, provided he or she is not using that exact page, the changes
would be in effect when they move to that page.
Also built into scohelp is
the ability to define "book marks." These are pages
(documents) that you have called-up and want to remember. Like a real
bookmark, these mark your place within a particular book, allowing
you to jump back to that exact page at the click of a button.
Although very limited in ability, scohelp
does provide a search mechanism.
So, after two chapters we know what an operating system does and what
goes into making the SCO UNIX product offering. With the
understanding of how things interact and what components are
available we can now starting thinking about what the system can do
for us. We are now ready to begin working with the system and see
just what we need to do to get the system to work for us the way we