I've posted another build of the Installation Guide with a TODO file. To clarify this a bit:
- The Known Issues are things that I can't check/don't know the answer to, but may be easy to fix.
- Version 0.9 will be a test release that is announced on the main fedora-list. 0.9 requires the screenshots to be put in place and the core sections "Disk Partitioning" and "Boot Loader" to be complete. I don't consider it necessary to complete all of the appendices to release 0.9, but before release we will have to remove any appendices that are not considered complete.
- Version 1.0 will be the release that is submitted for publication as the Fedora Core 3 Installation Guide.
- The issues listed as "not required for 1.0" are things that I would like to include sometime in the future, but won't delay releases for. Most are small additions.
Obviously, feel free to comment on, or propose amendments for, anything at all. --
Stuart Ellis s.ellis@fastmail.co.uk
Hi
- Version 1.0 will be the release that is submitted
for publication as the Fedora Core 3 Installation Guide.
It would be much better to have it as the FC4 guide. this probably isnt much different from the fc3 installation so it shouldnt be too much additional work for you.
when you announce your guide, you can post it to the fedora devel list and ask the developers for what stuff has changed in between fc3 and fc4 and verify that the guide is technical correct
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Read only the mail you want - Yahoo! Mail SpamGuard. http://promotions.yahoo.com/new_mail
On Tue, 25 Jan 2005 00:54:00 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
Hi
- Version 1.0 will be the release that is submitted
for publication as the Fedora Core 3 Installation Guide.
It would be much better to have it as the FC4 guide. this probably isnt much different from the fc3 installation so it shouldnt be too much additional work for you.
There is quite a long span between test1 and final, and judging by the previous release we have to assume that there will be a lot of changes made between test1 and final release. For example FC3 test 1 didn't have the Project Utopia stack, and that changed the whole OS when it went in. Xen, PUP and Fedora Extras are all in the early stages of development, and will probably require making multiple alterations to the documentation that the FDP supplies as they emerge.
Also, FC3 has another year of updates left (counting Fedora Legacy support), so it will remain relevant for some time.
For these reasons I would prefer to build a final release against FC3, and then fork development for an FC4 Installation Guide. Karsten's previous mail talked about splitting development between versions, and I agree with his comments.
when you announce your guide, you can post it to the fedora devel list and ask the developers for what stuff has changed in between fc3 and fc4 and verify that the guide is technical correct
I don't know how technical review will be arranged - the @redhat.com editors are best placed to say. --
Stuart Ellis s.ellis@fastmail.co.uk
Hi
Xen, PUP and Fedora Extras are all in the
early stages of development, and will probably require making multiple alterations to the documentation that the FDP supplies as they emerge.
I am not sure xen requires many externally visible changes that should be covered in the installation guide. its fairly experimental for fedora now and something that can probably be configured *after* the installation if required
pup and fedora extras can be covered as notes as expanded later
Also, FC3 has another year of updates left (counting Fedora Legacy support), so it will remain relevant for some time.
I am not saying fc3 is no more relevant. I am only concerned about yet another release getting out with no good docs targetting it.
For these reasons I would prefer to build a final release against FC3, and then fork development for an FC4 Installation Guide. Karsten's previous mail talked about splitting development between versions, and I agree with his comments.
ok. how about you doing the branch now and adding a todo for it adding notes on whats expected to change. I am actively following the fedora development tree (running rawhide) and lists (discussions on fedora extras, xen and what not) so I might be able to cover up the intial stuff necessary for getting a fc4 guide ready for the release. we shouldnt delay this waiting for something to be made perfect. a branch of the guide for fc4 is usable at this stage even now. lets get the ball rolling for this please
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? All your favorites on one personal page � Try My Yahoo! http://my.yahoo.com
On Tue, 25 Jan 2005 03:08:24 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
ok. how about you doing the branch now and adding a todo for it adding notes on whats expected to change. I am actively following the fedora development tree (running rawhide) and lists (discussions on fedora extras, xen and what not) so I might be able to cover up the intial stuff necessary for getting a fc4 guide ready for the release.
The best thing to do is look at the TODO list in the tarball, which is essentially the roadmap (as I see it). A branch is feasible at 0.9 (test release to fedora-list).
The easy way to see what "0.9" means is to grep through the Installation Guide FIXMEs and ignore the appendices, because we can drop them and still have a useful document. You will see:
- 2 sections to be written (Paul Frields has offered to tackle "Disk Partitioning"). - About three TECHQUERYs in the main text (Mayank is looking at these). - Screenshots (see separate discussions, I've made the masters and am unsure how to handle the EPS).
When these are resolved one way or another we can ship 0.9 to the fedora-list. At that point we have a publically available document and can start making noise at about it. I intend to ask for people to come in and help with 64-bit and PPC right from the initial post. With a visible document the FDP could also make a case for developers to become involved in technical review for 1.0. --
Stuart Ellis s.ellis@fastmail.co.uk
On Tue, 2005-01-25 at 13:01 +0000, Stuart Ellis wrote:
On Tue, 25 Jan 2005 03:08:24 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
ok. how about you doing the branch now and adding a todo for it adding notes on whats expected to change. I am actively following the fedora development tree (running rawhide) and lists (discussions on fedora extras, xen and what not) so I might be able to cover up the intial stuff necessary for getting a fc4 guide ready for the release.
The best thing to do is look at the TODO list in the tarball, which is essentially the roadmap (as I see it). A branch is feasible at 0.9 (test release to fedora-list).
The easy way to see what "0.9" means is to grep through the Installation Guide FIXMEs and ignore the appendices, because we can drop them and still have a useful document. You will see:
- 2 sections to be written (Paul Frields has offered to tackle "Disk
Partitioning").
- About three TECHQUERYs in the main text (Mayank is looking at these).
- Screenshots (see separate discussions, I've made the masters and am
unsure how to handle the EPS).
When these are resolved one way or another we can ship 0.9 to the fedora-list. At that point we have a publically available document and can start making noise at about it. I intend to ask for people to come in and help with 64-bit and PPC right from the initial post. With a visible document the FDP could also make a case for developers to become involved in technical review for 1.0.
Speaking of which, I have started work on the Disk Partitioning section, but discovered that my way of tackling it was, to be blunt, stupid. I decided to make the actual Disk Partitioning chapter purely about the mechanics of installation, and refer the reader to an additional appendix which would explain disk geometry and how to understand partitioning (how it works, and how to design partitioning for a particular system).
This means that I have to mark significant sections of the parts I'm writing with a conditional that qualifies them for "x86" architecture only. Can anyone remind me of the means for doing so in DocBook/XML? Feel free to respond offlist, otherwise I'll just search the archives when I have time, assuming the search engine actually works. :-)
I did a crummy job of estimating my time the last few weeks; work has demanded more of my hours than I expected, so the progress is slow. But I will redouble my efforts this week.
For anyone who cares, please also note my new email address. The frields.com domain owners shut the doors to their hosting business December 31st, and did not notify me. They still own the domain but it doesn't "do" anything for the time being. If you sent me anything since mid-December, and you have the ability, you may want to resend.
On Tue, 2005-01-25 at 13:01 +0000, Stuart Ellis wrote:
On Tue, 25 Jan 2005 03:08:24 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
ok. how about you doing the branch now and adding a todo for it adding notes on whats expected to change. I am actively following the fedora development tree (running rawhide) and lists (discussions on fedora extras, xen and what not) so I might be able to cover up the intial stuff necessary for getting a fc4 guide ready for the release.
The best thing to do is look at the TODO list in the tarball, which is essentially the roadmap (as I see it). A branch is feasible at 0.9 (test release to fedora-list).
The easy way to see what "0.9" means is to grep through the Installation Guide FIXMEs and ignore the appendices, because we can drop them and still have a useful document. You will see:
- 2 sections to be written (Paul Frields has offered to tackle "Disk
Partitioning").
- About three TECHQUERYs in the main text (Mayank is looking at these).
- Screenshots (see separate discussions, I've made the masters and am
unsure how to handle the EPS).
When these are resolved one way or another we can ship 0.9 to the fedora-list. At that point we have a publically available document and can start making noise at about it. I intend to ask for people to come in and help with 64-bit and PPC right from the initial post. With a visible document the FDP could also make a case for developers to become involved in technical review for 1.0.
Speaking of which, I have started work on the Disk Partitioning section, but discovered that my way of tackling it was, to be blunt, stupid. I decided to make the actual Disk Partitioning chapter purely about the mechanics of installation, and refer the reader to an additional appendix which would explain disk geometry and how to understand partitioning (how it works, and how to design partitioning for a particular system).
This means that I have to mark significant sections of the parts I'm writing with a conditional that qualifies them for "x86" architecture only. Can anyone remind me of the means for doing so in DocBook/XML? Feel free to respond offlist, otherwise I'll just search the archives when I have time, assuming the search engine actually works. :-)
I did a crummy job of estimating my time the last few weeks; work has demanded more of my hours than I expected, so the progress is slow. But I will redouble my efforts this week.
For anyone who cares, please also note my new email address. The frields.com domain owners shut the doors to their hosting business December 31st, and did not notify me. They still own the domain but it doesn't "do" anything for the time being. If you sent me anything since mid-December, and you have the ability, you may want to resend.
--- Stuart Ellis s.ellis@fastmail.co.uk wrote:
I've posted another build of the Installation Guide with a TODO file.
Thanks for summing up the issues and giving them a timeframe. Below are some responses (keeping 0.9 in mind). These might have already been discussed, in which case archive URLs would be welcome.
KNOWN ISSUES
- Need to find a simpler way of formatting a USB device with the Fedora boot image ("Beginning the Installation").
You ask for a simpler method because of (a) Differences in media handling and (b) directory layout
We could ask the fedora-devel for a standard method if it exists. Meanwhile, let's write the procedure as per FC3. We could start a maintainence file (!) that lists things (such as this) which need to checked with every release of FC. This would make maintaining the doc easier.
- "Network Configuration" section does not document wireless.
Your specific query: does Anaconda configure wireless interfaces?
I have Linksys WMP11v4 cards. They get no special treatment from Ananconda in FC2 and FC3. We could check with the devel guys what chipsets they support (if any).
- Kickstart option in Network Boot Services does not appear to work ("Configuring Network Installation Servers").
Haven't used kickstart ever.
---
My TODO (in order of the probability of them getting done :)
- Double check if Anaconda supports Wireless interfaces - Attempt on the missing sections/appendices - Get hold of a CompactFlash Card and a supporting BIOS and check whether it works as an install media or doesn't - Double Check if the Kickstart option in Network Boot Services works or not
! Mayank
________________________________________________________________________ Yahoo! India Matrimony: Find your life partner online Go to: http://yahoo.shaadi.com/india-matrimony
Hi
We could ask the fedora-devel for a standard method if it exists.
this is part of a larger problem. we need the development list to cc the docs list for major changes and document them when necessary. following the gnome development model for this would be possible. it requires more coordination than the current state. fedora docs at present seems to be very isolated from the developers who need to concerned about the lack of documentation
Your specific query: does Anaconda configure wireless interfaces?
I have Linksys WMP11v4 cards. They get no special treatment from Ananconda in FC2 and FC3. We could check with the devel guys what chipsets they support (if any).
http://www.redhat.com/magazine/003jan05/features/networkmanager/
scroll to the last section for more information. of course these might not be configured by anaconda at all
- Kickstart option in Network Boot Services does not
appear to work ("Configuring Network Installation Servers").
again something that requires more coordination and active partcipation from the developers. we should not rely solely on authors to ask different places to get these kind of information
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Yahoo! Mail - now with 250MB free storage. Learn more. http://info.mail.yahoo.com/mail_250
On Tue, 25 Jan 2005 03:14:28 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
Hi
We could ask the fedora-devel for a standard method if it exists.
this is part of a larger problem. we need the development list to cc the docs list for major changes and document them when necessary. following the gnome development model for this would be possible. it requires more coordination than the current state. fedora docs at present seems to be very isolated from the developers who need to concerned about the lack of documentation
I think that this a circular problem. Fedora and GNOME developers have seen the benefits of usability, so they push for better usability themselves. I don't think that documentation is seen as a critical part of developing useful software. Community documentation work is too fragmented to have a strong voice in development, and cannot point to any spectacular success in the same way that usability work has revolutionised GNOME.
Short version - if we want developers to invest their time on documentation issues then documenters have to produce work that is high quality and visibly successful. --
Stuart Ellis s.ellis@fastmail.co.uk
Hi
I think that this a circular problem. Fedora and GNOME developers have seen the benefits of usability, so they push for better usability themselves. I don't think that documentation is seen as a critical part of developing useful software.
the point is thou that documentation is critical factor for many people. developers even if they dont write all the docs themselves should consider it important enough to cc the list and announce the important changes that should be documented
gnome usability had a few important motivated developers concerned with it and moving forward inspite of the difficulties. we need a bunch of such people for the documentation team too. The document authors should not work in isolation. in many cases the work being documented is involved enough that its simply not possible to do so. When we have this installation document at 0.9, we can make some noise about this in the development list.
Community
documentation work is too fragmented to have a strong voice in development, and cannot point to any spectacular success in the same way that usability work has revolutionised GNOME.
thats because the distributions themselves are fragmented to create very integrated documents.. thats out of scope to be discussing here thou
my short version: get a 0.9 release out and make some noise about this for feedback in the users list and getting developers involved in the devel list
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Yahoo! Mail - You care about security. So do we. http://promotions.yahoo.com/new_mail
On Tue, 25 Jan 2005 05:25:50 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
Hi
I think that this a circular problem. Fedora and GNOME developers have seen the benefits of usability, so they push for better usability themselves. I don't think that documentation is seen as a critical part of developing useful software.
the point is thou that documentation is critical factor for many people. developers even if they dont write all the docs themselves should consider it important enough to cc the list and announce the important changes that should be documented
I tend to see it slightly differently. Unless there is an active documentation project and viable documentation, what basis is there for asking for other people to invest their time in any way ? So asking for technical reviews, CC etc. is reasonable only if there are community-supported documents.
--
Stuart Ellis s.ellis@fastmail.co.uk
Hi
I tend to see it slightly differently. Unless there is an active documentation project and viable documentation, what basis is there for asking for other people to invest their time in any way ? So asking for technical reviews, CC etc. is reasonable only if there are community-supported documents.
your document at version 0.9 would potentially be good enough and important to make some noise and generally keep developers aware of whats expected
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Take Yahoo! Mail with you! Get it on your mobile phone. http://mobile.yahoo.com/maildemo
On Tue, 25 Jan 2005 07:17:33 -0800 (PST), "Rahul Sundaram" rahulsundaram@yahoo.co.in said:
Hi
I tend to see it slightly differently. Unless there is an active documentation project and viable documentation, what basis is there for asking for other people to invest their time in any way ? So asking for technical reviews, CC etc. is reasonable only if there are community-supported documents.
your document at version 0.9 would potentially be good enough and important to make some noise and generally keep developers aware of whats expected
Well, there has to be base of contributors and documents for them to work with first, otherwise who would they be sending mails to ? :)
My hope is that posting a test release will attract a couple more contributors, and that things will continue to move forward. --
Stuart Ellis s.ellis@fastmail.co.uk
Hi
Well, there has to be base of contributors and documents for them to work with first, otherwise who would they be sending mails to ? :)
this list
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? Yahoo! Mail - You care about security. So do we. http://promotions.yahoo.com/new_mail
On Tue, 25 Jan 2005 11:06:26 +0000 (GMT), "Mayank Sharma" geekybodhi@yahoo.co.in said:
--- Stuart Ellis s.ellis@fastmail.co.uk wrote:
KNOWN ISSUES
- Need to find a simpler way of formatting a USB
device with the Fedora boot image ("Beginning the Installation").
We could ask the fedora-devel for a standard method if it exists.
That's one possible source of information (a longer comment is on my other mail). The issue is that the command-line specified is likely to be wrong because it is not guaranteed that your USB device will be /dev/sda1. So the ideal would be to specify a utility where the user can select from the available devices on their system.
I'm happy to drop the step-by-step instructions if we can't feasibly give specific instructions that will be true for most cases.
Meanwhile, let's write the procedure as per FC3.
OK. Again, the thing that we have account for in our text is that the dev nodes and mount directories are not guaranteed.
We could start a maintainence file (!) that lists things (such as this) which need to checked with every release of FC. This would make maintaining the doc easier.
I think that this is a great idea.
- "Network Configuration" section does not document
wireless.
I have Linksys WMP11v4 cards. They get no special treatment from Ananconda in FC2 and FC3. We could check with the devel guys what chipsets they support (if any).
This is where I apologise for having no document specification to point to. These points probably haven't ever been written down:
a) A hard requirement: our text has to apply to multiple architectures (32-bit PC, 64-bit and PPC), so architecture-specific references have to minimised. As an example - the text says "firmware, or BIOS", because BIOS is actually just the name of the 32-bit PC firmware.
So we can't reference specific manufacturers and models of hardware in the main text.
b) Objective: The IG text should document how to use anaconda to achieve things, rather than just stating what anaconda does.
Hence the question - what happens if one of the interfaces is wireless ? Does the user have to add more settings, or can they verify that the wireless was configured correctly because they will be able to see it listed as an available interface ? Is there anything else that the user will need to do, or be aware of, in order for the wireless to work (in FC3 you probably have to enable NetworkManager) ?
I don't know the answers to these questions...
c) Objective: the text must be useful without offering detailed information which is not likely to apply to individual readers. Unecessary information makes the information that is relevent to the specific user harder to focus on.
The best way I could think of to meet both b) and c) is to keep detailed, technical or highly information out of the main text. This is the logic behind putting "Network Logins" as an appendix, rather than including a description of the settings in the "System User" section.
- Kickstart option in Network Boot Services does not
appear to work ("Configuring Network Installation Servers").
Haven't used kickstart ever.
Don't worry about it too much, then. It can be fixed by whoever writes the Kickstart appendix, since they will have a working Kickstart setup that they can test against.
My TODO (in order of the probability of them getting done :)
Whatever you can do is helpful. --
Stuart Ellis s.ellis@fastmail.co.uk
--- Stuart Ellis s.ellis@fastmail.co.uk wrote: Hi Is there
anything else that the user will need to do, or be aware of, in order for the wireless to work (in FC3 you probably have to enable NetworkManager) ?
network manager is mostly a beta release and is disabled by default in fc3 for that reason. add a warning note if you are going to suggest using that in the guide
===== Regards Rahul Sundaram
__________________________________ Do you Yahoo!? The all-new My Yahoo! - Get yours free! http://my.yahoo.com
docs@lists.stg.fedoraproject.org
-
Mayank Sharma -
Paul W. Frields -
Rahul Sundaram -
Stuart Ellis