Portions of a conversation Stuart and I have been having offlist WRT the Fedora Installation Guide:
On Sat, 2005-03-05 at 18:29 +0000, Stuart Ellis wrote:
There are significant sections on RAID and LVM that (I think) are pretty much required, so that a new user can figure out how to set them up.
Very much agree. I don't think that we can reasonably say that LVM is just an advanced option any more, even if it's a pain to document. Having mind-bending amounts of less reliable storage available for peanuts makes these technologies pretty much mandatory...
That said, I think that many hobbyists (and I'll put myself in among them) still tend to use physical partitions as "directly formatted" ext3. I'm not planning on adding and removing disks on my home workstation, and neither are many users. Nevertheless, you and I are in complete agreement that RAID/LVM must be fleshed out in the installation guide... especially since anaconda uses LVM for automatic partitioning these days.
If I have to sacrifice those sections to get this thing out for FC4 test2, I will, but I will keep working on them nonetheless. I am currently using FC3 to do my writing, but I will have FC4 test1 (almost) as soon as it is issued.
This was really what I felt we needed to work out - there's enough stuff in the TODO to keep Mayank and I busy until you are ready, and IMHO it helps if we all stick to the same version (whether it's the latest or not). If you are happy to move up to test 1 then I'll do a roll-up release and switch development after test 1 comes out, with a new target of test 2 for a public beta release. What worried me was the risk of things drifting or getting into a muddle later if we didn't agree something at this stage.
Mm, hadn't thought enough about the ramifications, you're right. Look, I think it would be much easier to stick with FC3 until FC4 final is issued. I know that means we might be "off target" for a week or two until we update, but it's easier than trying to "track" changes between FC3, FC4t1 and FC4t2 -- just in case anaconda has some niggling change between test releases.
You can see what I've done at http://svn.frields.org if you are interested.
OK, I've read through them, but won't make any nit-picky comments since they're works in progress. Following from the above, though, it might be worth assuming that LVM is the standard way of doing a manual partition layout, and push that further up the text, perhaps even deprecating directly partitioning the drives (just a thought - I don't know if this is entirely reasonable). As a parallel, I ended up deprecating static IP addressing for anything other than servers, because I realised that it wasn't actually the best approach in most scenarios any more (NetworkManager, plus cheap DHCPing routers and WAPs all over the place).
See my comments above; 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.
However, injecting a discussion of LVM (or RAID) into the procedural flow about how to use the anaconda installer is a bit distracting, though. These sections exist to backstop the installation process rather than to push people toward a technology. They are enabling technologies for the situations that call for them. I'm not sure which version you saw and what I'd completed by the time I'd emailed you. Right now I plan on making frequent calls to the RAID and LVM subsections using <xref> where called for, and I think that will make everyone comfortable when they read it.
Another vague suggestion is that the Appendix might be easier to tackle by structuring it around the use cases (workstations and laptops would be probably use Automatic partitioning, or just have a separate /home) and maybe de-emphasising the hardware specifics. Most servers and workstations I've seen use IDE CD drives with SCSI hard drives and tapes, or (recently) just SATA. (S)ATA RAID is apparently now fairly common on enthusiast mainboards too, so I guess that the boundaries are getting very blurry.
Many legacy boxes are being coverted to Linux, however... which really proves your point. That's why I would like to de-emphasize the "let's explain technology" angle, and instead focus on the procedure first and foremost, referring to specific sections on enabling technologies where appropriate.
FWIW, I've written up a documentation plan to try to summarise for Mayank (and any future contributors) the aims and requirements I've been working towards with the text:
http://www.mythic-beasts.com/~hobb/main/index.php?pagename=InstallationGuide...
The current version is just a brain dump - comments and corrections are very welcome.
This is good info for anyone trying to contribute to the IG. One thing that occurred to me while reading: I think that relying on the built-in help screens of a program is not a commonly accepted method for doing system documentation. It definitely saves a little time, but in terms of a readable document, simply providing extra material in the absence of the basic procedural support is going to result in a document that's much harder to read. There's nothing wrong, for example, with simply reproducing what's already in anaconda in the IG, as long as the terminology is supported and the style is consistent. We have a couple documentation experts at work whom I will ask this question if I can get them off the keyboards long enough.
--- "Paul W. Frields" stickster@gmail.com wrote:
Portions of a conversation Stuart and I have been having offlist WRT the Fedora Installation Guide:
hey why is the conversation off list?
Regards Rahul Sundaram
__________________________________ Celebrate Yahoo!'s 10th Birthday! Yahoo! Netrospective: 100 Moments of the Web http://birthday.yahoo.com/netrospective/
On Tue, 8 Mar 2005 16:57:54 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
--- "Paul W. Frields" stickster@gmail.com wrote:
Portions of a conversation Stuart and I have been having offlist WRT the Fedora Installation Guide:
hey why is the conversation off list?
I initially sent a "how are things going" mail and Paul's posted the rest, so that we can carry on discussion here. --
Stuart Ellis
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.
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.
- Installation Guide Plan, and Anaconda vs. Installation Guide:
http://www.mythic-beasts.com/~hobb/main/index.php?pagename=InstallationGuide...
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.
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.
- 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. --
Stuart Ellis
On Wed, 2005-03-09 at 02:01 +0000, Stuart Ellis wrote:
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.
If I didn't feel that replies like "+1" were injurious to the continued existence of the English language, I'd write that here. The only quibble I have with anaconda is the fact that automatic partitioning doesn't create a /home partition. All the beginners I know hate it when they realize that their naive initial setup forces them to repartition later when they know what they are doing.
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
All the beginners I know hate it when they realize that their naive initial setup forces them to repartition later when they know what they are doing.
Even worse, if they must re-install with FC(n+1) within two or three months of their FCn installation. We need to liberate "/home" from the tyranny of the "/" oppression!
Cheers
On Wed, 9 Mar 2005 08:19:50 -0600, "Tommy Reynolds" Tommy.Reynolds@MegaCoder.com said:
Even worse, if they must re-install with FC(n+1) within two or three months of their FCn installation. We need to liberate "/home" from the tyranny of the "/" oppression!
As my small contribution to the cause, I've filed an RFE with a link to this discussion:
https://bugzilla.redhat.com/beta/show_bug.cgi?id=150670
--
Stuart Ellis
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=InstallationGuide...
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
On Fri, 11 Mar 2005 00:09:42 -0800, "Karsten Wade" kwade@redhat.com said:
On Wed, 2005-03-09 at 02:01 +0000, Stuart Ellis wrote:
It sounds like you should branch as soon as possible.
The key problem, really, is that I don't know how long it will realistically take to do some of the tasks, particularly as everybody is working in their spare time. For example, I don't actually know how long an edit takes for a document of this size. Which is is why I feel that I have to pass the buck and ask what other people feel is reasonable.
Where is the canonical SVN/CVS?
The canonical version is the latest release on the Website, uploaded from my workstation. Paul and Mayank are working on specific sections so merging isn't an issue at this stage. The need to eventually move into Fedora revision control is partly why I see multiple versions as an issue - as you say, at some stage we have to import into CVS, so I wasn't sure whether we ought to be importing IG3 and then branching for 4, or waiting until 4 and not branching until 5. I don't use an RCS in my work, so I don't know how this should be administered or what the pitfalls will be when we do it.
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?
Conceptual linking. I know a tiny bit about page design, but nothing about best practice where the user may be reading the document and information from the screen simultaneously. Paul offered to ask the documenters at his work.
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.
In all the scenarios I could think of where you wouldn't want to do it, you would be probably be using Kickstart or doing custom partitioning anyway, but obviously not everybody agrees, *shrug*.
--
Stuart Ellis
docs@lists.stg.fedoraproject.org
-
Karsten Wade -
Paul W. Frields -
Rahul Sundaram -
Stuart Ellis -
Tommy Reynolds