Bug 54985 - Missing documentation for configuring servers that lack GUIs
Missing documentation for configuring servers that lack GUIs
Status: CLOSED RAWHIDE
Product: Red Hat Linux
Classification: Retired
Component: rhl-cg (Show other bugs)
7.2
All Linux
medium Severity medium
: ---
: ---
Assigned To: Tammy Fox
Tammy Fox
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2001-10-23 18:56 EDT by Tom Moertel
Modified: 2007-04-18 12:37 EDT (History)
0 users

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2001-10-24 18:18:33 EDT
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 Tom Moertel 2001-10-23 18:56:29 EDT
From Bugzilla Helper:
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4+)
Gecko/20010914

Description of problem:
Regarding rhl-cg(EN)-7.2-HTML-RHI (2001-08-30T14:29-0400)

First, the docs are really shaping up.  Great work!

Now, on to the problem:

Many of the Customization Guide's chapters assume that the computer being
configured has X installed, despite that the standard RHL "Server"
installation does not include X.  Additionally, when the CG relies
exclusively upon GUI tools for customization, it often omits any
information about text-based alternatives.  For example, in Chapter 6,
"Network Configuration," the CG says, "To use the Red Hat Network
Administration Tool, you must be running the X Window System ..."  What if
X isn't available?  Nowhere else in the chapter is non-GUI configuration
addressed, not even a pointer to config-file man pages or an admission that
no convenient non-GUI configuration method exists.  The reader must read
the entire chapter only to discover that it provides no help.  The same
applies to chapters 18 and 19.

Even in chapters where text-based options are mentioned, the documentation
often makes the options hard to spot.  For example, Chapter 22 starts off
with the text, "To use printconf, you must be running the X Window
System..." but later contradicts itself by mentioning in passing that, "You
can also run printconf as a text-based application..."  A hurried reader --
and what sysadmin isn't hurried? -- could easily miss this important fact
by taking the first statement at face value and skipping the rest of the
chapter.

May I suggest that the entire CG be reviewed from a non-GUI perspective and
each chapter revised to state clearly in its introductory text what options
exist for both GUI and non-GUI configuration?    Something along these
lines would be great:

   Printers can be configured using both GUI- and
   text-based interfaces.  GUI-based configuration
   is described in 22.1.  Text-based configuration is
   described in 22.2. ...
   
In cases where no convenient text-based configuration method is available,
just say so.  Don't make readers comb the full length of the chapters
hoping to find some non-GUI advice that isn't there.  If there isn't any,
tell the reader up front:

    You can configure network settings using a GUI-based
    tool or by editing configuration files by hand. ...

Cheers,
Tom


Version-Release number of selected component (if applicable):


How reproducible:
Always

Steps to Reproduce:
1.  Read the CG.

Additional info:
Comment 1 Tammy Fox 2002-03-07 17:57:57 EST
We created the Customization Guide to 1) document all the new GUI configuration
tools and 2) provide intermediate content between the Getting Started Guide and
the Reference Guide. We have tried to make it clear when there is a TUI or
command line equivalent of the GUI tool. 

In the printconf chapter, I removed the statement that says you must have X to
run it and moved the existing sentence about printconf-tui into the list of ways
to start printconf.

The introduction to the Network Configuration chapter already contains:

If you prefer modifying the configuration files, refer to the Official Red Hat
Linux Reference Guide for information on their location and contents.

The command line version of RPM is explained first and refers the user to GnoRPM
for a graphical tool.

I have added a few sentences here and there explaining the command line
alternatives and pointing to the Reference Guide for information on modifying
configuration files by hand. 

I hope you will find the next version of the Customization Guide better.




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