Documentation status report

I’ve been smashing documentation bugs left and right since getting back from vacation, as well as searching out old documents and project pages and fixing ‘em up.

Most of the updates have been to the installation & Portage handbooks, but there are many changes to the other documentation, including the desktop guides for graphics cards, and my Xfce guide. There’s even a new doc on Logcheck, written by one of our developers.

Here’s a brief summary of what I’ve done in the last week:

New documentation:

• Logcheck guide: Thanks to phajdan.jr. bug 322223

Handbook updates:

• Change ccache recommendation; it’s really only for developers: bug 327945
• Use layman rather than gensync for working with Portage overlays: bug 305047
• Add another note on IA32 emulation in the kernel for (non-)multilib users: bug 326691
• Fix file verification process for the Alpha, AMD64, ARM, HPPA, IA64, and x86 handbooks: bug 283402. This was an old one: when we went to the weekly media autobuilds, Release Engineering signed the files with a new GPG key, and changed how the files were signed. All the handbooks need to be updated, as they still have the old keys and instructions from the previous release.
• Update installation instructions for the autobuilds. Completed Alpha, AMD64, ARM, HPPA, IA64, and x86: bug 283402, bug 292726, bug 260403. Still need to do PPC, PPC64, Sparc, and possibly MIPS, if they have sufficiently recent media.
• Use -march=core2 for recent Intel EM64T chips, rather than the old -march=nocona. Fix MCE section of kernel config. Add new Atom processor type: bug 323381
• Update Grub documentation links. Upstream removed all grub legacy instructions in favor of grub2, which won’t be stable any time soon. Fixed the handbooks and other docs to use the offsite Grub Wiki: bug 328679
• Fix a missing fstab. Gave ARM the same generic fstab example as the other arches: bug 328095
• category/package move for chkrootkit

Desktop doc updates:

• Xfce guide: Change USE flags for opera; no longer needs qt-static. bug 328087
• nVidia guide: Use new driver installation methods. Add links to xorg-server guide to get X configured before dealing with nVidia-specific issues. Update kernel and module info. bug 307481
• ATI FAQ: General cleanups. Add R800 (Evergreen) info. Remove old GATOS project text. Update Catalyst availability section.

Other doc updates:

• FAQ: Update Grub documentation link. Update gcc -march info for x86 and AMD64. Fix internal GuideXML code. bug 328679
• Quickinstall guides (x86, LVM2+RAID): Fix ccache recommendation. bug 327945
• LDAP guide: use more recent 2.3 configuration file shipped with the ebuild. bug 325497
• SHOUTcast guide: Miscellaneous typo fixes. bug 323401
• IPv6 guide: update net-dns/totd info now that it’s stable. Fix GuideXML and minor text issues throughout. bug 326771. This doc presents an ongoing problem, because it recommends a package it shouldn’t. I sent an email to the gentoo-dev mailing list asking for help with this one.
• AMD64 FAQ: Update Flash installation info. Adobe decided to drop 64-bit versions (again) beginning in version 10.1, and our developers had to mask 10.0 for security reasons. This means that there is no Adobe Flash for non-multilib profile users. And nspluginwrapper is (once again) too unstable, so 32-bit Flash with a 64-bit browser is not recommended. Probably will have to install firefox-bin or some other 32-bit browser. Stupid Adobe.
• UTF-8 guide: Fix wrong category for the Xfce terminal, leftover from when it was moved out of xfce-extra. bug 328977
• Fix metadoc index for retired developers and add logcheck guide entry

Project page updates:

• Overlays userguide: Extensive GuideXML, grammar, etc. rewrites to make the guide more readable and more helpful. Add more instructions for things like keywording packages per the Portage handbook. Add SCM homepage links. This series of updates was prompted by bug 305047, the gensync to layman change.
• GUIs: Update retired developers
• PR: Add note stating that PR does not offer user support, and list available support resources. Hopefully this will cut down on the amount of support requests the PR team receives in our inbox every month.

Website updates:

• IRC: Add the Qt project channel, #gentoo-qt. bug 328665

One of my fellow developers, jkt, has been helping out a bit in the last couple of weeks, closing bug 301840 and bug 325885. This was especially important when I was on vacation and then out sick. I’m always happy when someone besides me steps up and gets our docs into shape. Thanks, Jan!

So that’s about it. There are still plenty of open documentation bugs, but the list has shrunk significantly. My biggest project now is to finish the rest of the handbooks for the weekly autobuild instructions. The rest of our open bugs will require just as many hours and days to fix, as large portions of our handbooks and guides will need to be rewritten. Hopefully I can at least get the autobuild updates done in the next few days.