Emile Schwarz wrote:

>But things are not so dark; we must just have to want to stop for some times
>(minutes or hours depending on the subject) and ask ourselves what was
>show-stoppers when we were newbies; if we recall something, then we "just" 
>have
>to take a bit of time to write the steps to go ahead (I mean write the 
>steps to
>have the solution and go beyond that show-stopper). Another solution is to 
>ask
>newbies on the list to send their recent troubles to a special address, then
>after some days add a special documentation (tips for newbies); last 
>solution is
>(once more to take sometimes to do it) to start a fresh installation from
>scratch to a new machine and on a new hard disk; then note anything we 
>have to
>do (to change to the default values) to be able to install, boot and at 
>last run
>a piece of software.

Many of the problems we've run into are addressed in the FAQ that Colin 
Wood wrote.  For a number of years he was taking questions and answers 
from the mailing list and putting them into the FAQ, and maybe it's time 
to review this to see if there are new problems that need to be added to 
the FAQ.  Unfortunately not many new users look for answers in the FAQ, 
they seem to assume that the answer to their specific problem or question 
should be in the installation documentation at the point where they 
experienced the problem.  Not all installations go the same way, so it's 
difficult to anticipate all the problems people will run into during 
their particular installation.  Even if that were possible the resulting 
installation guide would probably appear to be inconsitent with most 
other users' installation experiences.  Technical documentation seems to 
come to two basic flavors; either a Dummy's Guide or a Reference Manual.  
The first is way to basic for all but the newest users while the second 
tends to be far to advanced for all but the experienced users and it 
makes for extremely poor reading since it's not a "How-To". (A bit like 
reading the dictionary to learn a language.)

I think there's room and a need for both types of Installation 
Documentation.  The "Dummy's Guide" (no offense intended to any new users 
here) is best written from the point of view of the novice/first-time 
user.  Most of us, having gotten past the initial installation, forgot 
all the minor details we stumbled over to get there. I'd be happy to help 
answer questions, review documentation and/or offer suggestions for this 
but I really think it needs to come from a real new user or users.

The Reference Manual is probably very much like the FAQ we have now. (And 
by the way, Dave Burgess's FAQ is also a very good source even for mac68k 
users.)  Maybe we need for someone with technical writing experience to 
step forward and volunteer to work on efforts like this. Here again, I'd 
be happy to help, but I'm not a technical writer.  (Being an old Fortran 
coder I've often used the excuse that I don't have to be accurate, only 
consistent in the first six characters.)

-bob