Reading the recent gentoo newsletter, I noticed this comment in the GUI installer thread on a newsgroup that no one seemed to really pick up on properly: [quote] I must also say that I actually wouldn't rate the docs so highly. There's a lot of them, but they're kind of a mess: scattered in different pages/hierarchies, often not adequately cross-referenced, and never, I mean *never*, helpful in anything less than a sunny-day scenario. Don't get me wrong; I highly appreciate the work that has gone into the docs and making gentoo what it is in general.[/quote] I suffered from exactly the same thing when installing gentoo for the first time recently. The guide is really good -- until something goes wrong. It basically assumes that nothing can go wrong. But things do go wrong, and when they do, a little more explanation of emerge/portage/ebuilds/USE-keywords would make a lot of difference to a newbie. Having a "Troubleshooting" section at the back of the guide would have helped a lot. A Troubleshooting section would not be a long list of the things that can go wrong and how to fix them. Instead it would describe useful gentoo-specific commands and techniques for isolating problems and learning more about what's going wrong. It would include the kind of things I learned from many of the helpful replies to all my questions on the gentoo forums. I imagine that such a section would mention installing gentoolkit; commands like ewhich, etcat, ufed, qpkg; describe the subtle difference in meanings between ebuild, emerge, and portage. Say where portage lists its packages and categories, so you can see what's available. Explain how to find out what configure options in a package match with possible USE keywords for it. How to tell masked packages from stable ones in /usr/portage/profiles/use.desc, and why you should suspect them when things go wrong. Stuff like that. Reproducible: Sometimes Steps to Reproduce: This suggestion is distilled from the long discussion with Sven that can be found in http://bugs.gentoo.org/show_bug.cgi?id=36346 It was buried and lost in the mass of discussion, I think.
It's kinda difficult to explain people how to use the various gentoolkit applications (and other tools) without assuming they have some Gentoo system they can work on. The installation instructions are meant to only talk about the installation. Gentoo is full of choices, but it's kinda difficult to write documentation if we want to explain all choices. Especially if we take into account the various tools etc. A troubleshooting document is something I'm hoping for some time now, but noone actually started writing up a draft. However, there is an idea on creating some sort of knowledge base in which FAQs, tips, explanations and alike are (dynamically) inserted. Such an (online) application should provide usefull hints to the users when they encounter unknown events. Would such a service suit your needs?
Yes, that would be okay, if not ideal. I think the most benefit lies in info on troubleshooting the installation, since after that gentoo is not too different to other Linux distros. > It's kinda difficult to explain people how to use the various gentoolkit > applications (and other tools) without assuming they have some Gentoo > system they can work on. Sure, but they do. It only has to be the system running from the CD, or if they got that far, the system they've partly installed and are trying to finish off the install for. So there's no problem there. > The installation instructions are meant to only talk about the > installation. Yep, but the troubleshooting should apply to mainly the installation. After that, gentoo can be learned about in normal ways and it's not too different to other Linuxes. > Gentoo is full of choices, but it's kinda difficult to write documentation > if we want to explain all choices. Especially if we take into account the > various tools etc. You don't have to explain all choices, just the useful tools that can be used to work out what's going wrong in the installation. I listed some of the things I found useful in solving all my installation problems: ewhich, etcat, ufed, qpkg. *Examples* of some useful emerge commands and options would be another useful. A useful troubleshooting guide for the installation would only have to be about 5 or 6 pages long, I think, to be a big help. That's my gut feeling.
Okay; I'll mark this as a duplicate of that effort then. *** This bug has been marked as a duplicate of 37442 ***
BTW, on the troubleshooting specific questions, this could be easily inserted in the Gentoo FAQ.
To be honest, having just read right through 37442, which ends up being a request to set up a Gentoo knowledge base (estimated effort: <shrug> 6 man months?) for solving general problems, I can hardly see how it relates to my suggestion (Troubleshooting gentoo installation section; estimated effort: 1 week). Sigh. In fact, I'll predict that the 37442 idea will just silently die, since it can be pretty well achieved by either searching on the gentoo forums or on google. Doing that, and working out which ones might relate, judging from their subject lines, then reading all the possible matches to see, is much, much harder than just reading a troubleshooting section in the install guide. Sven, your final suggestion (add a troubleshooting section to the FAQ), would do, but you're suggesting it for a bigger topic than I am here. It'd do, though, even if it would be more work for the documenters. That suggestion seems to tie up with this suggestion, though, not 37442. But this one is now marked as a duplicate of that, and so resolved. Won't that mean bugzilla can't be used to keep in the todo list? get lost because
Np. I assumed the implementation of such a KB would be sufficient to tackle this. If not, well then I reopen and keep it in the bugzilla until someone hacks up a nice troubleshooting document :)
No, a KB would be simply equivalent to the present system (searching via Google or the forums). But it does have the advantage of requiring lots more work than my suggestion. A Troubleshooting section would be simpler and more direct. If you're hinting that I should write it if I want it ... I could, but I have too many other higher priority pieces of work. Also, from our discussions, you and I don't see eye to eye in these areas, so I have serious doubts you'd incorporate it even if I did put in the effort. That's my frank assessment I'm afraid.
I would not incorporate it in the handbook but as a separate guide.
*** Bug 38513 has been marked as a duplicate of this bug. ***
There's now a Gentoo/x86 Tips 'n Tricks document pertaining to the installation instructions. It contains a chapter on "Fixing Errors/Issues" which can be used to provide information on how to troubleshoot issues you might come across during the installation. The tips 'n tricks document can very well contain interesting commands to find more information and such. Afaik, this is exactly what is requested by this bugreport (or at least to a great extend). http://www.gentoo.org/doc/en/gentoo-x86-tipsntricks.xml
Sounds great. But apologies, I couldn't find it at the given URL http://www.gentoo.org/doc/en/gentoo-x86-tipsntricks.xml, nor could I find it from a simple search around or from looking at http://www.gentoo.org/doc/en/ and skimming for the URL, nor by searching for the word "tips". (That only revealed a different document.) Sorry for being a bit thick about this. luke
Yes, someone played with our webnodes and they're still not catching up on CVS.
