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:
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.