User Guides vs. Troubleshooting Guides

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

First off, I would like to thank all those members for their wonderful support. It's really awesome to have such a level of camaraderie amongst a diverse group of people with a common passion! I personally think this is the best damn forum I've ever been a part of! (now that I've buttered you all up...hehe

)

I am a Customer Support Engineer for Cisco Systems (TAC), so I am extrememly familiar with technical documentation (we have one of the biggest documentation databases on the planet!), but for the past 5 years, I've noticed a lack of a certain TYPE of documentation ( that most hardware/software companies are guilty of, gentoo included). Sure...I can find out HOW to set up anything I want, but what if I set it up and it DOESN'T work as expected? Where's the doc that shows me HOW to FIX it? Check the Forums you say...I do and have, of course, but a lot of the important info gets buried, deep within the bowels of the Forum database or is so scattered amongst many separate threads and out of order! It's hard to make sense of it sometimes. Now, here at Cisco, we've slowly been adding more detailed documentation that explains how to fix it, if it's broken after an initial configuration. I've actually have made several, such guides for myself over the years. My problem is I would gladly help create these doc's for gentoo, but don't know "my ass from my elbow", when it comes to Linux (well...that's pretty harsh, but I have to follow directions still...I'm not to the level where it's all in my head, YET!)

I guess I wanted to see what everyone elses feelings on this subject are! If there are such doc's already and I've overlooked them, please disregard this post!

ckdake · l33t Joined: 10 Apr 2003 Posts: 889 Location: Atlanta, GA

That sounds like a great idea to me. Here, there are "stickies" that are common problems, but to have a HOWTO FIX stuff website would be a great help. Perhaps a troubleshooting section in "the Gentoo Handbook"
_________________
http://ckdake.com/

Neje · n00b Joined: 04 May 2003 Posts: 71 Location: Netherlands

Well, there are "Frequently Asked Questions" and "Documentation: Tips and Tricks" sections in the forum that try to achieve this. Looking in "Duplicate Threads" is also a nice trick if you suspect you simply overlooked something and searching doesn't pay off.

What might be nice is a collection of Frequently Solved Installation Problems, they may be in order of where in the installation things go wrong. For instance: 5 d: Code listing 13 (nano won't work, illegal instruction). Solutions: Usually due to wrong livecd/tarball, check if your cpu architecture matches your livecd/tarball.
_________________
"It's some kind of electronic computer."
- Tin Tin, Thunderbirds

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

Neje...I agree that there's PLENTY of useful information on the Gentoo website. I just happen to think there should be guides like this:

1. Troubleshooting X/KDE/GNOME/etc...
2. Understanding and Troubleshooting Log Error Messages
3. How to defend against a Gentoo attack! :lol:

4. etc...

In these guides, either condense all the helpful forum threads or write nice, step-by-step instructions. For example, if I need help figuring out why after I emerge'd KDE, setup my Window Manager, and made sure X was configured correctly, it doesn't load. Where do I turn to? Hours of reading posts, doesn't sound like fun nor something I like to do (I do this ALL day at work!)...

Does that make more sense? Thanks for the replies...

Neje · n00b Joined: 04 May 2003 Posts: 71 Location: Netherlands

I didn't mean that there is enough troubleshooting material available, I meant that there are already forum sections where troubleshooting info should go. It's just that maybe a more orderly structure (maybe the forum format isn't right for that though) would be helpful, and that there should be more troubleshooting info . Like "the top 10 causes why startx doesn't start x". Or "reading and understanding emerge system compilation errors for dummies".

So, I know what you're saying, but it's probably a project in itself. A start would be if there were sticky posts (or maybe they could be in a separate forum section), like "post here if you had the problem that startx didn't start x, please describe how you solved the problem". And then maybe reorganize the info, cut out some redundant stuff, and make a guide out of it.

Step-by-step guides will always be tricky in the case of Gentoo, though, because of the customizations and manual configuration no Gentoo system is like another. That's what makes it hard to support in the first place, and makes these forums so (over)populated with friendly people who know that the writer of the "friendly manual" may not have known all the things that could go wrong.
_________________
"It's some kind of electronic computer."
- Tin Tin, Thunderbirds

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

Gotcha!

I bet there's some very industrious gentoo techie out there, willing to start such a project...There always is!

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

Kinda off the topic, but I hate cluttering up a froum with countless posts, when I already have one going!

I am emerging kde (for the 3rd time), since I didn't follow the steps correctly the 1st time. I am wondering if seeing "errors" while the compilation is going on is normal? I mean, if I watch the messages that scroll by, occasionally I see a "no directory found, can't find this , can't load that, etc..." Is that normal? The 2nd time I emerge'd it (90 or so files needed) it seemed to have failed at the end. I ran the "emerge -p kde"and there were things left to emerge still. Does anyone have any idea why I have to keep emerging kde over and over? It's alomost done with the 3rd one. Then I'll see if it works!

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

Update...This is what is happening and I do not know if this is normal behavior.

When I "emerge -p xxxxx" (kde, samba, kfce4, apache, etc...), I get the messages, checking dependencies followed by I would emerge in this order (you know how it goes). I then type "emerge xxxxx" and it runs through the script like it's supposed to. At the end it says it's done, I check with another "emerge -p xxxxx" and the same file is still listed there. The common denominator is they all have "base" in their filename.

example:

xfce4-base/xfce4-4.0.1

I still can't get kde to work, so I think this has something to do with that. Any advice would greatly appreciated. Thanks!

cyrillic · Posted: Sun Dec 14, 2003 8:18 pm Post subject:

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

AHHH...I see. Makes sense. Now all I need to figure out are which files I need to edit to get KDE to work! Still can't get it to run... :cry:

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

Besides the XFree86 Config file (which is already setup for my hardware and working), which files do I need to edit and how do I switch window managers (twm sucks terribly!)? I would like to have X start on boot up and use xfce4! Thanks, guys!

Neje · n00b Joined: 04 May 2003 Posts: 71 Location: Netherlands

What you're looking for is /etc/rc.conf. Here's the relevant part of mine:

slimpinto · n00b Joined: 07 Dec 2003 Posts: 46

woo hoo...It keeps looking better and better all the time! Thanks guys!