Fedora Installation Guide Schedule

[Karsten Wade]

On Wed, 2005-03-09 at 02:01 +0000, Stuart Ellis wrote: 
> My original mail ended up being very long, so I'll try to do better and
> keep my comments to a readable length:
> 
> - Release schedule, and what version(s) of FC to write against:
> 
> My main concern is to minimise the workload for everybody, so I'm happy
> to fall in line with whatever arrangements other people feel are best
> for their writing, editing etc.  Probably sounds customer-unfriendly,
> but the users can only be helped if we can produce and maintain a
> complete doc with the resources that we have.
> 
> What I'd personally like is secondary, but ideally would be:
> 
> - To release a credible-looking test document for feedback, and to
> attract more contributors (hopefully some that can test against x86-64
> and PPC).  Credible may mean FC4 test 1 at this point, I don't know.
> - To complete a 1.0 draft in time for it to be edited, so that...
> - An Installation Guide for FC4 appears as soon as possible after FC4
> final is released.
> - To have a 1.0 Guide for FC3, if Karsten is willing to edit two
> documents.

It sounds like you should branch as soon as possible.  I don't mind
editing two, I really only have to edit the first and read a diff.
Okay, well, that might not be so easy ... may be an excuse to get
xmldiff working.

I'm in favor of you putting up a test version as soon as you are
comfortable.

Where is the canonical SVN/CVS?

Can we branch on your server and keep the history when adding it into
Fedora CVS?  My instinct says, no.  

How can we do this cleanly?

One idea is to make Fedora CVS canonical, check-in the latest code and
branch it, then you can put the two branches in your SVN.  When you have
rw to the module, you can move the code back in, and Tammy or I can do
manual merging of content.

Eww.  That sounded so ugly.

Maybe Tammy or Elliot have a better suggestion.

> The reasons for the last are that many people are very slow to upgrade
> (I'm still having to try to persuade people on forums to get off RH9),
> and that I think that it would be useful to start figuring how to
> practically support multiple versions as soon as we can.

Agreed.  That is a challenge.  People still use RHL 9 docs all the time,
especially for Fedora Core.

> - Installation Guide Plan, and Anaconda vs. Installation Guide:
> 
> http://www.mythic-beasts.com/~hobb/main/index.php?pagename=InstallationGuidePlan

This is good.  It highlights the differences between the target Fedora
user and the target Enterprise Linux user.  Stuart pointed out that we
can't assume a Fedora Core user knows anything about Linux or UNIX
concepts, or even reads complex English.

> One of the (many) ideas that I've tried to compress into the "plan" is
> that an Anaconda graphical installation is kind of self documenting
> already, in that you can read the screens and understand what to do *if*
> you speak Linux and understand the terms that are used.  Which suggests
> that a lot of the value of the Installation Guide is in explaining what
> the options mean, and describing the features that can't be seen on the
> graphical screens.  I wouldn't like to have sections which just repeat
> the contents on the screen without adding anything - this isn't very
> well expressed.

That is wise thinking.

> I'd be very interested in hearing how professional documenters link
> program screens with the documentation - I don't think that the current
> layout quite gets this right.

I'm not sure what you are asking here.  Do you mean hyperlinking screens
to docs, or conceptual linking?

> - Recommending LVM and deprecating direct partitioning:
> 
> > I still think LVM is not a requirement for an
> > installation just because the installer uses it in the "autopilot" mode.
> > It does that in order to support a broader base of administrators who
> > don't know yet that they might want LVM. As a consequence the guide must
> > address LVM. 
> 
> This was really my point in a nutshell - IMHO everybody who manually
> partitions a drive ought to use LVM, even if they don't realise it when
> they install the system.  At work we now mandate the MS equivalent of
> LVM on all Windows servers because we discovered in testing that it was
> impossible to guess exactly the right partitioning setup for 100Gb+ of
> storage in advance, and destructive repartitioning is, well, not a valid
> option once a system is live...
> 
> > However, injecting a discussion of LVM (or RAID) into the procedural
> > flow about how to use the anaconda installer is a bit distracting,
> > though.
> 
> Yes, thinking about it these concepts are advanced however you document
> them (manual partitioning is probably an advanced topic, as a whole), so
> probably ought to be pushed out to an Appendix as much as possible.  The
> only reason that I routinely go through the manual partitioning on
> workstations is get /home away from the root partition.

I tend to think of the default FC install as representing a base set of
best practices.  LVM, in this case, has received lots of field testing,
and resolves many of the nagging problems of an install that happens to
a Linux user:  how to partition, should you partition differently, what
is this partition stuff anyway and where is my c:\ drive?

Therefore, linking to an appendix that explains LVM and partitioning
(overview) is great, and we definitely want to support the default
choice here with our docs.   IMO.

I'm also in favor of /home being a separate partition by default.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
              Learn, Network and Experience Open Source.             
Red Hat Summit, New Orleans 2005   http://www.redhat.com/promo/summit/