Red Hat Bugzilla – Bug 54985
Missing documentation for configuring servers that lack GUIs
Last modified: 2007-04-18 12:37:44 EDT
From Bugzilla Helper:
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4+)
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
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. ...
Version-Release number of selected component (if applicable):
Steps to Reproduce:
1. Read the CG.
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.