Changes and Updates to Installation chapter

[Marc Fonvieille]

On Sat, Jan 06, 2007 at 11:35:31PM +0100, Niclas Zeising wrote:
> >
> >Hello,
> >
> >(Quick answer)
> >
> >You think about xorgcfg(1)?  It is possible to add the dozen of
> >xorgcfg's screens but it will remain difficult for the newbie cause the
> >same "weird" questions will be asked, but this time, via a graphical
> >interface.  I mean using "Xorg -configure" or xorgcfg(1) is quite the
> >same thing, we have no FreeBSD specific GUI to configure X11, so we
> >cannot "compete" with the Installers you seen on some Linux distribution
> >or some desktop oriented FreeBSD derivatives.
> 
> A dozen screens from xorgcfg(1) is not needed, neither is it what I was 
> looking for.  What I meant was that the instructions we have are quite 
> clear, at least to get a graphical user interface working. Maybe a 
> how-to somewhere or something. I haven't read the X chapter of the 
> handbook, maybe that's sufficient as it is, as long as it's current.  It 
> would be good to have something to point at.
> I'm not saying we can or should "compete" with the desktop oriented 
> Linuces or PCBSD or the like, just that we need some instructions on how 
> to configure X.
>

It's difficult to talk about something, if you didn't check if it is or
it isn't documented.

> >
> >>The biggest change I suggest is removal of most of the bits regarding 
> >>networking, and putting them in some sort of "Simple networking" chapter 
> >>in the networking section instead.
> >
> >I think it's not possible and not a good thing to remove things that the
> >user can or will meet/need during installation process (don't forget
> >some people get installation files via Internet, etc.).
> >
> >>I think we only should have 
> >>instructions on how to get an internet connection up and working in the 
> >>workstation sense, i. e. how to be able to surf the net and so on.
> >
> >Well if the user's Internet connection setup is not done via DHCP you
> >cannot easily describe a general way to set up the Internet access.
> >If the connection uses DHCP, it's fine since this configuration can be
> >done at installation time in the parts you want to remove.
> 
> Noted. You can also set up a static IP-address from sysinstall, but it 
> doesn't matter.
> 
> >
> >>WWW/FTP-servers, NFS and so on doesn't belong in an installation chapter 
> >>in my opinion.
> >
> >By Installation chapter, the idea was covering everything that can be
> >done during the installation process with our installer (currently
> >sysinstall).  It's possible to configure everything (but X11) during the
> >installation, which is very interesting for some users.
> 
> Ok.
> 
> >
> >>I also had an idea of adding a chapter to the networking section which 
> >>talks about tcp/ip-networks in general, subnetting, routing and so on. 
> >>Is that too much of topic?
> >>
> >
> >It's not what does the "27.2 Gateways and Routes" section and some other
> >sections?
> 
> Maybe. The idea came from a short discussion when someone (ceri iirc) 
> updated the networking chapters to use CDIR-notation instead of 
> mentioning the old A/B/C-class networks.  I thought we maybe needed some 
> sort of explanation of CDIR and other network related stuff somewhere. 
> If there is such a place already, we can always expand that instead.
> 

This notation is not explained in details in the Handbook.

> >
> >>This is just suggestions. As said before I would like some input on this 
> >>before continuing to do the actual work. I have a more detailed list 
> >>about what's needed to be done, but since it's mostly small fixes I 
> >>realized the above summary better describes what has to be done. I can 
> >>type it down and post it if someone asks for it.
> >>
> >
> >From my point of view, we need to update the current text and
> >screenshots to match the current installation process (the current steps
> >the user will meet during the installation).  The X11 part in the
> >current Installation chapter can be reduced, in fact changed to match
> >what is done during the use of sysinstall(8).  I don't think we need to
> >remove things cause they may be "difficult" to understand by the user,
> >we must keep post-installation steps.
> >
> 
> I never intended to remove the "difficult" pieces of the installation 
> chapter.  The rationale behind moving most of the networking bits was to 
> have one place (the networking section) explain almost everything 
> regarding networking.  If most people want them to stay where they are, 
> they stay, with an update of course.
>

I think you should spend time reading carefully what is currently in the
Handbook (the whole Handbook) and how the parts, chapters and sections
are organized.
According to what I read, I feel you misunderstand the role and the
range of explanations expected in the Installation chapter.
While I'm there, another remark on the fact why some things should not
removed from that chapter: if we think about non-english-speaking
persons, when we start the translation of the Handbook the Installation
chapter is most of time the first chapter to be translated and sometimes
the only one (or the only one to be up to date).  Well I don't say the
current chapter is perfect, I just think at first it should be updated
to the current installation steps then later, once it's up to date, we
could see if the chapter layout needs to be changed; and a such way will
be faster.

-- 
Marc