Gentoo Forums
Gentoo Forums
Gentoo Forums
Quick Search: in
idea for incrasing incrase Q/A
View unanswered posts
View posts from last 24 hours

 
Reply to topic    Gentoo Forums Forum Index Gentoo Chat
View previous topic :: View next topic  
Author Message
GNUtoo
Veteran
Veteran


Joined: 05 May 2005
Posts: 1919

PostPosted: Thu Jun 08, 2006 7:40 pm    Post subject: idea for incrasing incrase Q/A Reply with quote

Gentoo is a higly customisable distribution and it's instalation method doesn't help much:
a lot of people make error while installing,some common examples are:
*missing a step
*miss spelling

theses problems are normaly solve by the forum but only if:
*others forums member understand the problem
*the problem is very common and not to complex(there isn't a lot of things to check)
*motivated people are there at the time he post his problem(chance)
Another thing is that theses people could help for more important things if common problem are resolved another way

so some scripts can easely cope with theses problems
An example is a script that check,for a particular problem,if the person has made all steps

for example if someone hasn't the sound working:
-it will ask if he installed alsa or OSS
->alsa
then it will ask the way he wanted to install it(built-in,modules,userspace)
->modules
then it will try to look if the modules are loaded
if not he will search if they are built,otherwise it will search if the right alsa uttilities are installed,then he will look if the services are started and if they are added at the boot services.
then it will look at the volumes and then it will ask if the person has connected his speakers...

common error can also be integrated into theses scripts

i already posted to the dev mailing list but ther were too much ocupated with somethig else
Back to top
View user's profile Send private message
NeddySeagoon
Administrator
Administrator


Joined: 05 Jul 2003
Posts: 54028
Location: 56N 3W

PostPosted: Thu Jun 08, 2006 10:24 pm    Post subject: Reply with quote

new_to_non_X86,

What you are proposing is called a fault diagnosis tree. Its often written on paper in the form of a flow chart.

Where would the effort come from to generate and maintain these scripts?
Rather than fixing the problem after the event, its much better to prevent the problem in the first place. That could be done with changes to the install guide by adding check steps.

Like, run top, check your swap is shown.
run mount, check that /dev/hda3 is mounted on /mnt/gentoo and that /dev/hda1 is mounted on /mnt/genoo/boot.
Download a stage 3 tarball, check its right for your CPU.

Extensions to the docs like this would keep a lot of installs on the rails because errors would be caught as they occured, when they are easiest to fix, not after several more steps, when there is some unpicking to do.
_________________
Regards,

NeddySeagoon

Computer users fall into two groups:-
those that do backups
those that have never had a hard drive fail.
Back to top
View user's profile Send private message
GNUtoo
Veteran
Veteran


Joined: 05 May 2005
Posts: 1919

PostPosted: Thu Jun 08, 2006 11:12 pm    Post subject: Reply with quote

NeddySeagoon wrote:
new_to_non_X86,

What you are proposing is called a fault diagnosis tree. Its often written on paper in the form of a flow chart.

Where would the effort come from to generate and maintain these scripts?
Rather than fixing the problem after the event, its much better to prevent the problem in the first place. That could be done with changes to the install guide by adding check steps.

Like, run top, check your swap is shown.
run mount, check that /dev/hda3 is mounted on /mnt/gentoo and that /dev/hda1 is mounted on /mnt/genoo/boot.
Download a stage 3 tarball, check its right for your CPU.

Extensions to the docs like this would keep a lot of installs on the rails because errors would be caught as they occured, when they are easiest to fix, not after several more steps, when there is some unpicking to do.

shell scripting is easy
so it could come from the users...
it could also help to improve the install guides

but you're right
updating the guide is better but how are they designed
is there any flow shart that the user could upgrade?
Back to top
View user's profile Send private message
NeddySeagoon
Administrator
Administrator


Joined: 05 Jul 2003
Posts: 54028
Location: 56N 3W

PostPosted: Fri Jun 09, 2006 10:45 am    Post subject: Reply with quote

new_to_non_X86,

The offical Gentoo documentation is written in what called Guide XML. There are a few tools to help with it too.

I don't share your opinion about shell scripting being easy. It depends how accomplished you are already.
Many users are not interested in contributing to Gentoo, they just want to use it. They want it to work and they don't want to debug it.
Anything that comes from users has to be maintained by the devs. If a user contributes something and maintains it, they are almost a Gentoo developer.
_________________
Regards,

NeddySeagoon

Computer users fall into two groups:-
those that do backups
those that have never had a hard drive fail.
Back to top
View user's profile Send private message
GNUtoo
Veteran
Veteran


Joined: 05 May 2005
Posts: 1919

PostPosted: Fri Jun 09, 2006 4:40 pm    Post subject: Reply with quote

thanks...
mabe i'll contribute to the documentation when my english will be a little better
can the documentation use the gfdl?
(for articles comming from the wiki)
or the gfdl/creative common if i want to add some documentations(compatibility with the wiki)?

mabe i'll contribute to the colinux doc if i can find a openoffice document i made on this

by the way i think that gentoo is nearly perfect it only need Q/A and certain minor improovement

what's the difference between the gentoo documentation and the wiki?
how do the documentation team work?(because i only have windows 2000 and in italian and not windows XP)
Back to top
View user's profile Send private message
NeddySeagoon
Administrator
Administrator


Joined: 05 Jul 2003
Posts: 54028
Location: 56N 3W

PostPosted: Fri Jun 09, 2006 6:14 pm    Post subject: Reply with quote

new_to_non_X86,

The gentoo documentaion team produce, or at least have editorial contol over the offical gentoo documentaion. That link is to the English version. The wiki is not offical documentation - anyone can edit it, its just useful.

Since the Gentoo documents are available in many languages, there is probably no need to write in English. Translation can be a two way process. explains more.
_________________
Regards,

NeddySeagoon

Computer users fall into two groups:-
those that do backups
those that have never had a hard drive fail.
Back to top
View user's profile Send private message
GNUtoo
Veteran
Veteran


Joined: 05 May 2005
Posts: 1919

PostPosted: Fri Jun 09, 2006 11:49 pm    Post subject: Reply with quote

NeddySeagoon wrote:
new_to_non_X86,

The gentoo documentaion team produce, or at least have editorial contol over the offical gentoo documentaion. That link is to the English version. The wiki is not offical documentation - anyone can edit it, its just useful.

Since the Gentoo documents are available in many languages, there is probably no need to write in English. Translation can be a two way process. explains more.

thanks i'll send my unfinished work(in bad english) to the maintainer of the colinux doc

there is also the fact that some docs need to be updated such as the colinux doc

so i'll send some howto to gentoo instead of the wiki

others less usefull will stay on the wiki
Back to top
View user's profile Send private message
heavydwitstyle
n00b
n00b


Joined: 24 Nov 2005
Posts: 44

PostPosted: Tue Jun 13, 2006 3:48 pm    Post subject: Reply with quote

I think the Gentoo install handbooks are great. I'm fairly new to Gentoo and have been following them quite closely, they have never let me down. I did multiple test installations on virtual machines with no problem and will be soon re-deploying my HTTP server with Gentoo.


Thanks to all those who wrote the fantastic documentation!


- Heavy-D
_________________
Dual Core - Pentium D 805 - 2 x 2.66Ghz
2048MB DDR533 Crucial Memory
2x 320Gb WD SATA2
---
MacBook Pro running OS X 10.4.8
Back to top
View user's profile Send private message
Drone4four
Apprentice
Apprentice


Joined: 09 May 2006
Posts: 247

PostPosted: Wed Jun 14, 2006 4:45 am    Post subject: Reply with quote

Here is what I think. Being new to programming and Gentoo, I know exactly what the original poster is referring to. Namely, following the Gentoo handbook to install the amd64 version, I’ve made numerous trivial mistakes which have prevented me from completing the install. To avoid new Gentoo users making the same mistakes I have, my suggestion is to insert special notes perhaps on the side. Obviously we can’t predict every single misunderstanding new users make, but what we can do is focus on certain key prolem areas. The areas from the handbook which I had tremendous difficulty with are:

1. grub
https://forums.gentoo.org/viewtopic-t-122656-start-225.html

2. special notation of CXXSFLAG with “{$__}”
https://forums.gentoo.org/viewtopic-t-467790-highlight-.html

3. notation of “/BOOT” and “/ROOT” in the fstab

4. symlinks
https://forums.gentoo.org/viewtopic-t-471166-highlight-.html

I agree with heavydwitstyle: the existing Gentoo documentation project is spectacular, but there is room for improvement. Given the size and popularity of Gentoo, I believe pushing to improve already the greatest documentation is a reasonable goal for our community. Especially for users who are new to Linux, at least my half dozen grievances would be a good start.

This forum thread should be read by the developers who are able to implement or debate our proposals. Where should we look in order to make these ideas a reality? Who are the documentation team members responsible for considering our suggestions for the Gentoo handbooks?
_________________
My rig:
IBM Personal System/2 Model 30-286 - - Intel 80286 (16 bit) 10 Mhz - - 1MB DRAM - - Integrated VGA Display adapter
1.44MB capacity Floppy Disk - - PS/2 keyboard (no mouse)


Last edited by Drone4four on Mon Jun 19, 2006 8:10 pm; edited 1 time in total
Back to top
View user's profile Send private message
synss
Apprentice
Apprentice


Joined: 08 Mar 2006
Posts: 282
Location: Dijon > Berlin > Tokyo > Nürnberg > München

PostPosted: Thu Jun 15, 2006 3:57 pm    Post subject: Reply with quote

1st: Gentoo doc is great!!!

new_to_non_X86 wrote:
so i'll send some howto to gentoo instead of the wiki

others less usefull will stay on the wiki


Don't be exclusive, send your docs to both gentoo and the wiki if it is not too much work. The important stuff should also go to the wiki for anyone to find it, not only the trivial.
_________________
Compress portage tree
Elog viewer
Autodetect swap
Back to top
View user's profile Send private message
Rukie
l33t
l33t


Joined: 26 Jan 2004
Posts: 692
Location: SE Wi, Home of cheese and cowtippers.......

PostPosted: Fri Jun 16, 2006 5:13 pm    Post subject: Reply with quote

I'm often prone to making mistakes during installs, but something that I would like to point out is the learning experience that it gives you! Many times I have learned from my simple mistakes about linux, and now my mistakes are fewer but more complex, leading me into new knowledge. I think the handbook is adequate :) If you make it TOO simple, well, you lose that noobishness learning experience. Heck, I'm installing gentoo right now on another machine and its taken me a week :p From stage 1 however, now I'm just waiting on packages to compile :-D (kde-meta xorg (modular) gnome, open office, firefox, etc )
I say take advantage of the mistakes.
_________________
Gentoomania! Support the Open Source!
http://www.rukie.ath.cx
Back to top
View user's profile Send private message
VLegacy
n00b
n00b


Joined: 06 Aug 2004
Posts: 24
Location: Virginia, USA

PostPosted: Tue Jun 20, 2006 4:43 am    Post subject: Reply with quote

A checklist in the handbook could help prevent users from missing steps. For example, on the right side of the page next to each step or few steps could be a checkbox and the step's (or group of step's) title. A button could also be provided every so often (maybe after each section) which would tally the steps for the section and inform the user if there were any he missed.

I think Neddy's idea for "check steps" is a good one, and would help catch mistakes born of typos.
Back to top
View user's profile Send private message
Gooserider
Apprentice
Apprentice


Joined: 30 Dec 2005
Posts: 165
Location: Universe, Milky Way Galaxy, Solar System, Earth, North America, USA, MA, North Billerica

PostPosted: Sat Jun 24, 2006 3:50 am    Post subject: What I think would be most needed in the install docs... Reply with quote

I'm a mid level Linux User, and have installed Gentoo once, late last year using the 2005.1 download and manual. The manual was very good as far as it went, and as long as I was careful about my typing, it was fairly straightforward. I did have to go back a couple times to fix things, but that was my fault, and mostly the corrections weren't terribly painful.

What I did that saved me a fair amount of grief was to use the VT's and have different Gentoo docs open in VT 2+ while running the configuration program in VT1. In many cases this let me just copy and paste the relevant commands as needed. It might be nice if this was spelled out in the manual for the newbies - the peices are there now, but you need to be familiar with Linux and VT stuff to know how to put it together. However most folks probably wouldn't need it, and that is a minor point.

The "error check" steps suggested earlier would be good, but there are two areas that I would see as MUCH more useful to put some energy into. They were the things that I had the most problems with initially and still feel that they might be causing me problems still.

The first area deals with the install itself, and the parts that I had trouble figuring out how to handle...

I'm going through the current (2006) http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?style=printable&full=1 manual to compare it with my recollections and to see what has changed.

1. Give LOTS more details in Sect 5e (CFLAGS, CXXFLAGS, etc)
I know it isn't possible to cover all the options, but at least the major ones would help such as:
[*]A chart comparing MARCH flag to processor type[*]
[*]A discussion of O flags, and why a given flag might be better for a particular type of system[*]
[*]Known "causes problems for many" flags[*]
[*]A list of other popular flags and why / why not use them[*]

2. LOTS more info on USE FLAGS (Sect 6b.)
Again I know it isn't possible to cover all of them, but it would seem possible to me that a table could be created with the major "almost everyone uses" applications and what USE flags should (or shouldn't) be set in anticipation of emerging them later. Or, if it is true, something to the effect of "don't try to set USE flags unless you have a specific reason to" might be reassuring.

The second major area I would like to see added / expanded is the "Where do I go from here?" section after you have finished the basic installation.

Currently there is a lot of good info on adding additional Gentoo related stuff like Portage and it's related tools, and other administration related stuff, but there is not much about getting from the Gentoo command prompt to a functional graphical desktop (or a server, or whatever).

I don't think this needs a lot of manual writing, but more a list of the common tasks that a user might want to perform (install X, install a windows manager, install an environment like KDE / Gnome, etc.) in roughly the order they should be done with a pointer for each task to an appropriate documentation source.
_________________
Box 1: P2 Celeron 400, 320mb RAM, 80GB HD, Cirrus Logic 4614/22/24 sound card, ATI 3D RAGE PRO AGP 1X/2X (sound & video onboard)
Box 2: AMD Athlon 2500+ 512mb RAM, 80GB HD, Gigabyte K7 Triton (Nvidia) mobo, GeForce2 video
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic    Gentoo Forums Forum Index Gentoo Chat All times are GMT
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum