>>>>> On Fri, 09 Sep 2005 10:00:48 +0200, Mathias Friman <[EMAIL PROTECTED]> >>>>> said:
> Whatever you read below, I just love FAI. It has simplified my work for > about two years now, and I am really grateful for having it to lean > on. :) I've been on the list for about a year and a half now, and > I follow all discussions with interest. Thank you very much for these complements. Did you fill out the FAI questionnaire yet? :-) http://www.informatik.uni-koeln.de/fai/questionnaire > How does the list and the author feel about a complete remake of the > FAI documentation? In the past I got very different feedback about the documentation. Most say it's very usefull, but also a couple of people claimed that it's bad or not so usefull. > excellence of FAI to my fellow technicians, I have developed a > document (currently only in .pdf-format) that includes examples Please make it available on the internet. I would love to read it. > The people I work with have a long experience of the Microsoft (*ahem*) > platform and have only basic knowledge of Linux, mostly as users. The primary target group for FAI are experienced sysadmins. IMO, you can't set up an cluster or a larger computer infrastructure if you do not know how NTP or DNS has to be configured or if you do not know how you like to partition your harddisk. Once I ask a FAI user how likes to install a cluster of 20 nodes with FAI if he wants to use NIS. He did not know what this was. In FAI, you have to answer a lot of questions youself about your computer infrastrucure, before setting up FAI. If you do not have the knowledge to do this, is not easy to use FAI. In my talks about FAI, I tell about a two level approach. The senior sysadmin should create FAI classes and write all config files (especially the customization scripts) for theses classes. Then, a junior admin (or M$ user with less Linux knowledge) can take a new computer and just has to assign the classes to this new computer before installing the computer. The junior admin does not need to know all the details to performing an installation. He only has to read the documentation of the classes to decide which classes to use for a certain computer. > Personally, I think that the current FAI documentation is aimed at > already committed Debian GNU/Linux administrators, but leaves a lot of > catching up for those newly saved souls that decides to switch platform. I the FAI documentation, I tried not to explain common Linux tasks. For example I do not want to explain the differences between primary and logical partition, or what TFTP, NFS or PXE is. I think there is a lot of other documentaion about theses things, that do not need to be repeated in the FAI docu. But maybe it should list some topics that a FAI user should be aware of before starting with FAI. IMO distributed information on certain topics are better than repeating things all over again. > The documentation of FAI is rudimentary in some areas and could be hard > to grasp for a person newly introduced to Linux. I aggree with you, but I'm not sure if the FAI guide should cover these topics. > It also has no pictures to simplify complex textual > explanations. I would also like to include some graphics, but I did not had the time to create some. Also when including graphics, ASCII format of the documentation will not be supported any more. > The present documentation of FAI covers about sixty pages of written > text. A single book describing a less advanced product like Microsoft > RIS and MSI packaging never encompass less than 500 pages. Even though > FAI for Debian GNU/Linux is a lot more flexible and configurable, the > documentation only describes the default setup. Some people tell me, that they even do not like to read all the sixty pages. IMO people like to read fourty pages, but not 500. > My idea was to thouroghly and meticulously document the example > classes simple, advanced and beowulf included in FAI In FAI 2.8 we rewrote most simple example, but did not documented them very well. The advanced and beowulf examples are not maintained (tested) for a long time, and also need some clean up and better documentation. I think that may help a lot. > subroutines/tasks, helper scripts as ftar, install_packages, > mkdebmirror, fai-divert and so on. Every fai command has a man page, and I try to explain most things in the man page. IMO it makes no sense to repeat those information in the FAI guide. I prefer to point the users to the man page (and hope they read the man pages). But you are right the the subroutines, some variables and some internal structures are not documented well. Since we will rearrange the source code for FAI 3, we should start to document these things after the new source structure is finished. I makes no sense to do it know and then to rewrite the documentation because the source code was reorganised. > There is of course nothing wrong with asking and answering basic > questions multiple times. However, if this can be avoided by improving > the FAI documentation, I think that it is a thing that should be done. One question is, which things should go into the FAI guide, which should be managed by the FAI wiki page. > I'm working on a synopsis for the documentation which I was thinking of > publishing on this list if there is an interest for a revised > documentation. Please do not understand we wrong. I thing it's a great idea to improve the documentation, and I like to see your proposals. But I pretty sure that we should not extend the documentation to 500 pages :-) by just repeating some basic stuff. Maybe a FAI tutorial (a step by step intro) would be good for the Linux beginners. > Thomas and all involved in the development, thanks again for a great > tool. :) Thanks for your feedback. -- regards Thomas