So there are 10 handbooks at http://www.gentoo.org/doc/en/handbook/ for various architectures, such as 'x86', 'sparc', 'amd64', 'ppc', 'ppc64', 'alpha', 'hppa', 'mips', 'ia64', and 'arm'. Most of these handbooks are quite similar, except for the small portions that are architecture-specific. It is easy for a beginning user to end up on a page for the wrong architecture, inadvertently copy and paste configuration instructions for an architecture-specific step, and then end up with a cryptic compilation or portage error. Encountering such an error can cause lots of users to abandon their installation of Gentoo. So to lessen the chances of anybody making such mistake(s), there should be red warning boxes in the handbooks just above the portions with architecture-specific instructions, warning the user that those instructions are architecture-specific, and to make sure that they are on the page appropriate for their architecture. Might also be a good idea to include a link back to http://www.gentoo.org/doc/en/handbook/ inside these red warning boxes advising the user to go there to find the correct page for their architecture. Reproducible: Always
yes...if you click the right link, you get the instructions for that arch. we can't put warnings throughout the handbook saying "don't do this if you're on arch $foo." that would be distracting and irresponsible. we can't save the user from making the mistake of clicking the wrong link.
Well, as long as the users are going to be human they will make mistakes, and that should be recognized, and the product made in such a way that it is easier for the users to figure out what they are doing wrong. Perhaps the warning icons can be made to be small so that they are not that obtrusive. And there aren't that many architecture-specific steps anyway, but if one of those is done incorrectly then the whole installation is hosed.
