Jyothi Srinath wrote: > On 04/11/09 03:08, Ben Rockwood wrote: >> 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. >> > Hi Ben, > > Thanks for your helpful comments and feedback about the overall > structure and contents of the book. > And it is heartening to know that you found this document improved and > useful. > > I will try to get some of your feedback into the book for the June > release, and some of them may be deferred until the next release.
If you'd like help with the writing I'm happy to give it a try, so long as you can help me edit it back into proper tone (I tend to write in an informal voice). Just point me at the source. benr.
