I reviewed the first chapter and skim through the rest of the document. Here's my overall opinion about the first chapter.
For the first chapter, the overview, I think it needs much more general information. I think the existing information in the first chapter is focused too much on the details without giving people an good top level overview. I think some information on the following should be included in the overview chapter: - A very high level view of how AI works. Currently, it goes straight into talking about the service and client model. For me, that's kinda confusing. Since this is a user guide, perhaps we should talk about how the whole thing work from a user's perspective. Maybe a picture or a flow chart or something that talks about the user's experience, instead of giving a technical description of the service and client components. - Talk about the different components that make up the server, ie: the server uses a web browser, DHCP, DNS...etc... Also talk about how the client and server interact. By talking about the different components, people will have a better understanding how everything interacts and why things have to be setup a certain way. This will be helpful in case something is wrong, it will help people debug the problems more easily too. - The term "blue print" and "manifest" is used all over. But sometimes blueprint is used and sometimes manifest is used. I think it is better to have a section that gives the definition of the terms and used only 1 term for the rest of the document. Some other detail comments: ------------------------------------------------- - Page 5, first sentence of chapter 1. I don't think this sentence is correct. For the AI, I think you want to convey the idea that Open Solaris can be installed hands-free, and both x86 and SPARC systems can be installed using this tool. - Page 5, "What is the Automated Installer?" section This paragraph talks about clients contacting web server...etc.. This is too much detail in the implementation. When I read this sentence, I thought that as a client, I can use a web browser to contact the web server and find out what I can install from that server. - Page 8, comparsion to solaris jumpstart. Does it make sense to have a table that provides side-by-side comparison of the different functionalities between jumpstart and AI? It's much easier to read than lengthy paragraphs. ---Karen Barbara.Lundquist at sun.com wrote: > Install gang, > > We'll take a look at, and make review assignments for, the alpha draft > of the AI documentation tomorrow during our team meetings. Docs > include 1) a new wiki "cover page" for all the install docs and 2) the > revised AI main document. > > We will not review installadm(1M) man page during the meeting. > > Docs are posted at: > > 1) New Install Docs Wiki > (This is pre-alpha, but the idea is that one wiki "cover" page will > have listing of major install topics (AI/DC/Snap/installer), sorted by > user role, with links to the content. So far, only a few topics are > listed, for only AI, with no links yet.) > > http://wikis.sun.com/display/OpenSolarisInfo/Installation+Topic > > 2) AI main document - Alpha draft > (This is a major rewrite with alot of input from Ethan.) > http://www.opensolaris.org/os/project/caiman/files/AIinstall.pdf > > 3) installadm(1M) man page > (We'll need to confirm reviewers for this, but it's not posted today.) > > Barbara > > > > > > > > > > > _______________________________________________ > caiman-discuss mailing list > caiman-discuss at opensolaris.org > http://mail.opensolaris.org/mailman/listinfo/caiman-discuss
