Jyothi Srinath wrote: > Hello Documentation Community, > > The OpenSolaris 2009.06 Image Packaging System Guide is ready for review. > The pdf is located at : > http://opensolaris.org/os/project/pkg/files/ips.pdf > > This is a beta document and some links may point to older documentation. > > Please review and send in your feedback by April 20th (or sooner!).
Thank you for the invitation to review. Let me first point out that this is a fantastic document vastly improved over prior attempts. Here are a handful of non-absolute opinions for consideration: * Chapter 2 should include a parallel section to the existing "What is an IPS Package?" to address in completeness what is an image. * Chapter 2: Both sections "pkg(1) Uses FMRIs" and "Publicsher versus Repositories" seem incomplete. A very solid understanding of what is an image, what is a package, what are the types of images and packages, what are publishers, what are repositories, and what are the inter relations between all these elements needs to be concretely established before moving on. * Chapter 4: I didn't feel like "partial images" was every properly explained. Is it a big package? Or perhaps a system snapshot? I'm not sure. Furthermore, there are no partial image examples in the chapter. * Chapter 4: Figure 4-1 is confusing. Perhaps it simply is a concept that does not require a figure... it simply says to me "systems are images, images can exist within a system, or within a zone"... but no more. It thus feels incomplete. * Chapter 8 should follow chapter 5; they are logically joined. In reading I read in the order: 2,3,4,5,8,7,9,6. Speaking more generally about chapter 5. I think this chapter needs some fleshing out. The content is good but should be re-section. I think most people are going to approach this book with the question "How do I create a package?" The answer is found in Chapter 5 "Advanced IPS Commands". The table of contents will not direct you there, but rather if you thumb through the examples speak for themselves. I think of the contents in this way: Chapter 1: Introduction Chapter 2: IPS Concepts Chapter 3: IPS Packages for Users (Managing Packages) Chapter 4: IPS Images for Users (Managing Images) Chapter 5: IPS Packaging for Developers (Creating Packages) ... Chapter 8: IPS for Publishers (Creating Repositories) Chapter 9: IPS for Publishers (Mirroring Repositories) Chapter 6 should fold into Chapter 8; Chapter 7 should be an appendix. Additionally, I think it would be exceptionally helpful if there was a non-trivial package creation example added as an appendix, in which there is an example of perhaps creating a local repo, building some fairly simply GNU software package (for the purposes of being real world) and adding it via pkgsend to the repo directly and not as a SVR4 pkg. I hope thats helpful. I'm really pleased by this document, even as is its vastly superior to its predecessors that I've seen. benr.
