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. Thanks, Jyothi -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/docs-discuss/attachments/20090413/e3e3c18f/attachment.html>
