Bug 498991 - multiple suggested changes to F11 Preview Install Guide
Summary: multiple suggested changes to F11 Preview Install Guide
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Fedora Documentation
Classification: Fedora
Component: install-guide
Version: devel
Hardware: All
OS: Linux
medium
medium
Target Milestone: ---
Assignee: David Nalley
QA Contact: David Nalley
URL:
Whiteboard:
Depends On:
Blocks: 494832
TreeView+ depends on / blocked
 
Reported: 2009-05-04 17:50 UTC by Patrick C. F. Ernzer
Modified: 2010-01-04 06:12 UTC (History)
2 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2010-01-04 06:12:13 UTC
Embargoed:


Attachments (Terms of Use)

Description Patrick C. F. Ernzer 2009-05-04 17:50:41 UTC
Hello, just went through the preview of the F11 install guide. My comments are below.

The notes are pretty terse sometimes, please update this bug or grab me on IRC if you want some sections fleshed out more.

Installation Guide
Installing Fedora 11 on x86, AMD64, and Intel® 64 architectures

Edition 1.0


  - http://docs.fedoraproject.org/install-guide/f11/en-US/pdf/Installation_Guide.pdf is only 20 pages long, a test or a problem at PDF generation?
  - 1.2. Download Files:
    + it's sha256sum from F11 onwards, c.f. http://fedoraproject.org/wiki/Features/StrongerHashes
    + strongly suggest explaining how to burn an ISO, a link to http://docs.fedoraproject.org/readme-burning-isos/ should be enough to avoid people writing the iso as a file onto the medium.
    + alternatively remove all text on ISOs from 1.2. as 2.4.1. explains it in the necessary detail and has the link
  - 1.5. Perform Post-installation Steps: should link to Chapter 15. Firstboot and http://fedoraproject.org/wiki/FirstBoot
  - 2.1.1. From a Mirror: our infrastructure is smarter nowadays, http://download.fedoraproject.org/.../Fedora-11-Preview-i386-DVD.iso will actually point to a mirror, so this section of the guide should be revised to reflect that.
  - 2.4.2.2. USB Image Creation in Linux: liveusb-creator should be mentioned as it has a GUI, ideally it would be mentioned before livecd-iso-to-disk
  - 2.6. How Do I Start the Installation Program?: modern boards hava quite frequently a key to press to temporarily change the boot order, "Press F12 for temporary boot device selection" or "F8 for boot device selection". IMHO we should point that out before going on about BIOS and other things that may scare newbies. Suggested wording; "Many modern computers allow you to temporarily alter the boot device order without changing BIOS settings. You will see a message akin to "Press X to select boot device" which allows you to boot from the Fedora Installation medium while retaining your original settings. Please refer to your computer's manual." and then continue with the paragraph about entering BIOS (aim being here to not send hapless users into BIOS setup unless absolutely necessary)
  - 3.2. Is Your Hardware Compatible?: is really slim and useless to a newbie as there is no HCL for Fedora. Can we please at least have a blurp about smolt, something along the lines of "while it does not constitute an official hardware compatibility list, smolt (http://smolt.fedoraproject.org/) will tell you how other Fedora users are rating their hardware and thus assist you in your hardware purchasing decision" (or just refer to section 8.3.1. where we link the LinuxQuestions.org Hardware Compatibility List), also add a pointer to 15.4. Hardware Profile (so the user understands that sending his info is valuable)
  - 3.3. Do You Have Enough Disk Space?: should just link to the HD space requirement bit in the release notes
  - 3.4.1. Alternative Boot Methods:
    + the dd example is very dangerous as sda is nowadays most certainly the users's primary HD, can we please use sdz instead of sda in the example
    + that section also must point out that this procedure will erase the USB pen drive completely.
  - 3.4.2. Making an Installation Boot CD-ROM: should link back to 2.4.1. instead of paraphrasing it.
  - 3.5.2. Preparing for an NFS install: are you sure no_root_squash is really necessary? 
  - Figure 7.2. should be removed or replaced with a current screenshot (text mode had storage simplified)
  - 7.3.1. Booting the Installation Program on x86, AMD64, and Intel® 64 Systems: same comment as for 2.6.
  - 7.4. Selecting an Installation Method: should also give the repo=... option and point users to https://fedoraproject.org/wiki/Anaconda/Options
  - 7.5.1. What If the IDE CD-ROM Was Not Found?: I am not sure if that is still hdX or if nowadays it's sdX, please verify.
    FWIW, neither http://fedoraproject.org/wiki/Anaconda/Options nor /usr/share/doc/kernel-doc-*/Documentation/kernel-parameters.txt seem to list the hdX= option
  - 7.12. Keyboard Configuration: need to explain what the difference between latin1 and plain is.
  - 7.14. Upgrading an Existing System: need to have a note explaining that the install medium may not contain all necessary packages (Fedora vs Fedoar Everything) and it should mention preupgrade.
  - 7.14.3. Upgrading Boot Loader Configuration: should have a blurp about grub not doing ext4
  - 7.15. Network Configuration: should explain that localhost and localhost.localdomain are special (c.f. /etc/rc.sysinit) and a good choice for most users.
  - 7.22.2. Rescue Mode: should explicitly say that any install medium (CD, DVD, PXE) can do 'linux rescue'. Just pointing to 17.2. Booting into Rescue Mode seems to be enough.
  - 7.23.2. Customizing the Software Selection: could use a one liner stating tha the 'Everything' install is no longer there (then again we ditched that a while ago, so I'm not usre how many users we expect to be baffled by the absence of this option)
  - 8.2.1. Problems with Booting into the Graphical Installation: should advertise the new xdriver=vesa boot paramater from section 2.3. of the release notes
  - 8.3.2. Saving traceback messages without removeable media: we can post to bugzilla from anaconda nowadays, please add a paragraph about that.
  - 8.3.5. Other Partitioning Problems: with grub not doing ext4 but ext4 being our default FS in F11, please add a line "an ext3 formatted /boot partition if / ius ext4 or btrfs)
  - 8.3.6. Are You Seeing Python Errors?: check with clumens how early the saving to bugzilla is possible, then add 'from step... on you can ... (same comment as for 8.3.2.)
  - 8.4.1. Trouble With the Graphical GRUB Screen on an x86-based System?: needs small blurbs on:
    + timeout=0
    + rhgb
    + quiet
  - 8.4.3. Problems with the X Window System (GUI): should explain that one can do yum groupinstall 'GNOME Desktop Environment' (or XFCE or KDE (K Desktop Environment) or X Window System) after installation. Just pointing at 16.3. Switching to a Graphical Login seems to be enough)
  - 8.4.4. Problems with the X Server Crashing and Non-Root Users: F11 does (quite rightly) not allow root to log onto X, so text needs changing.
  - 8.4.5. Problems When You Try to Log In: idem. So add a blurp on how to change to VT2 (or any other text console)
  - 8.4.8. Problems with Sound Configuration: s-c-soundcard is no more, we ditched that a while ago, section needs rewriting
  - 9.1.4. Specifying the Installation Method: AFAIK it's repo=... nowadays and not method=...
  - 9.2. Enabling Remote Access to the Installation System: the package containing vncviewer is tigervnc nowadays, not vnc.
  - 9.2.1. Enabling Remote Access with VNC: if one starts text mode, nowadays anaconda asks if one wants to use VNC. c.f. release notes
  - 9.6. Using the Maintenance Boot Modes:
    + it's called Memtest86+
    + please add "You should let Memtest86 complete multiple rounds, ideally leave it running over night or over a w-e" and a reference to the FAQ at http://forum.canardpc.com/showthread.php?t=28864 to show we're not blowing smoke when recommending multiple rounds.
  - 10. Installing Without Media: really needs to speak about preupgrade, it's a good feature, we might as well point users at it.
  - 11.5.7. Performing the PXE Installation: might benefit from a link to gPXE project, I do 90% of my installs over the network and gPXE saves the day when a NIC lacks PXE.
  - 12.1. VNC Viewer: same comments as for 9.2. and 9.2.1.
  - 12.2.1. Direct Mode: idem
  - 12.4. References: idem
  - 13. Kickstart Installations: I trust the contents of this is always in sync with https://fedoraproject.org/wiki/Anaconda, if not, please add a link at the beginning of the chapter in a 'note' type box. (happened twice in the past that install guide and anaconda pages diverged after a while, confusing users as only one had correctly up2date information)
  - 15.2. System User: should have a 'note' type field explaining (again) that root login to X is disabled in F11 and that it is quite important to make a user.
  - I'm not sure the warning about 'Synchronize system clock before starting service' is still necessary. In F11 ntpd and ntpdate initscripts do have "Required-Start: $network". Please check with maintainer of ntp RPM.
  - 16.2. Finishing an Upgrade: please replace this with 'package-cleanup --orphans' bit from http://fedoraproject.org/wiki/YumUpgradeFaq or at least add that part.
  - 18. Upgrading Your Current System: again a chapter that will benefit from the mention of preupgrade
  - E.1. GRUB: once again, please explicitly mention that grub does neither ext4 nor btrfs at the moment. 
  - E.2. Installing GRUB: tell users to install grub on all RAID1 members. c.f. http://tldp.org/HOWTO/Software-RAID-HOWTO-7.html#ss7.3
  - E.6.2. Configuration File Directives: as the OS from Redmont has trouble booting if it is not on the first HD, there may be value in also explaining the 'map' command. An example;
Windows XP resides on the 4th disk, in order for it to boot, it is necessary to make XP believe it is on the 1st disk like so;
title Games Loader
	map (hd0) (hd3)
	map (hd3) (hd0)
	rootnoverify (hd3,0)
	chainloader +1
in order for it to boot, it is necessary to make XP believe it is on the 1st disk like so;
title Games Loader
	map (hd0) (hd3)
	map (hd3) (hd0)
	rootnoverify (hd3,0)
	chainloader +1
c.f.: http://grub.enbug.org/Booting
  - E.8.3. Related Books: please make clickable links to the RHEL Deployment Guide
  - F.2.4. The /sbin/init Program: should explain about upstart (http://fedoraproject.org/wiki/Features/Upstart)
  - F.3. Running Additional Programs at Boot Time: not sure we still use /etc/rc.serial , please check.
  - F.4. SysV Init Runlevels:L should be replaced with more details on upstart

Comment 1 Ruediger Landmann 2009-05-05 00:02:54 UTC
PDF is only 20 pages long -- this is a bug in Publican 0.44 (#492689). Basically, Publican builds the PDF up to the point where it encounters the first table in the document then crashes.

Thanks for the comprehensive list of issues, Patrick!

Comment 2 eric 2009-06-10 22:29:01 UTC
Can any of these be closed?

Comment 3 Ruediger Landmann 2009-06-10 22:37:48 UTC
No -- this excellent list of issues came in several days after the document was frozen for translation. 

Now that F11 is out the door, I'll be working through this list in the next week or two, with a view to closing these and other bugs against the guide by the end of June.

Comment 4 Joel Uckelman 2009-06-19 12:21:18 UTC
Note that the file README-BURNING-ISO-<lang>.txt still refers to SHA1 instead of SHA256 checksums, also.

Comment 5 Ruediger Landmann 2009-07-13 06:29:47 UTC
I've just committed fixes for most of these issues -- just have to get developer input on a few more before I can close this bug. 

Commit ba322d8dcc461379d0dc79e9a2a16f3b87d7d606

Comment 6 Ruediger Landmann 2010-01-04 06:12:13 UTC
As far as I can tell, all these issues were resolved by the time we published the F12 guide.

Many thanks once again Patrick for the extensive and extremely helpful feedback.

Cheers

Ruediger


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