View previous topic :: View next topic |
Author |
Message |
GNUtoo Veteran
Joined: 05 May 2005 Posts: 1919
|
Posted: Thu Jun 08, 2006 7:40 pm Post subject: idea for incrasing incrase Q/A |
|
|
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 |
|
|
NeddySeagoon Administrator
Joined: 05 Jul 2003 Posts: 54266 Location: 56N 3W
|
Posted: Thu Jun 08, 2006 10:24 pm Post subject: |
|
|
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 |
|
|
GNUtoo Veteran
Joined: 05 May 2005 Posts: 1919
|
Posted: Thu Jun 08, 2006 11:12 pm Post subject: |
|
|
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 |
|
|
NeddySeagoon Administrator
Joined: 05 Jul 2003 Posts: 54266 Location: 56N 3W
|
Posted: Fri Jun 09, 2006 10:45 am Post subject: |
|
|
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 |
|
|
GNUtoo Veteran
Joined: 05 May 2005 Posts: 1919
|
Posted: Fri Jun 09, 2006 4:40 pm Post subject: |
|
|
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 |
|
|
NeddySeagoon Administrator
Joined: 05 Jul 2003 Posts: 54266 Location: 56N 3W
|
Posted: Fri Jun 09, 2006 6:14 pm Post subject: |
|
|
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 |
|
|
GNUtoo Veteran
Joined: 05 May 2005 Posts: 1919
|
Posted: Fri Jun 09, 2006 11:49 pm Post subject: |
|
|
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 |
|
|
heavydwitstyle n00b
Joined: 24 Nov 2005 Posts: 44
|
Posted: Tue Jun 13, 2006 3:48 pm Post subject: |
|
|
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 |
|
|
Drone4four Apprentice
Joined: 09 May 2006 Posts: 247
|
Posted: Wed Jun 14, 2006 4:45 am Post subject: |
|
|
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, Ive 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 cant 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 |
|
|
synss Apprentice
Joined: 08 Mar 2006 Posts: 282 Location: Dijon > Berlin > Tokyo > Nürnberg > München
|
Posted: Thu Jun 15, 2006 3:57 pm Post subject: |
|
|
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 |
|
|
Rukie l33t
Joined: 26 Jan 2004 Posts: 692 Location: SE Wi, Home of cheese and cowtippers.......
|
Posted: Fri Jun 16, 2006 5:13 pm Post subject: |
|
|
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 (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 |
|
|
VLegacy n00b
Joined: 06 Aug 2004 Posts: 24 Location: Virginia, USA
|
Posted: Tue Jun 20, 2006 4:43 am Post subject: |
|
|
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 |
|
|
Gooserider Apprentice
Joined: 30 Dec 2005 Posts: 165 Location: Universe, Milky Way Galaxy, Solar System, Earth, North America, USA, MA, North Billerica
|
Posted: Sat Jun 24, 2006 3:50 am Post subject: What I think would be most needed in the install docs... |
|
|
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 |
|
|
|
|
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
|
|