On 04/13/09 17:13, Ben Rockwood wrote: > 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. > Hi Ben,
Thanks for the offer to add content to the IPS document. If you can send me the content (a text file would be fine) for some of the specific topics by April 22nd, I can edit it and include in the document. This would be the most effective way to get your content into the doc in time for deliveries to G11N and the 2009.06 release. Content for the following topics that you have mentioned would be very useful: 1.What is a image? What are partial images? 2.What is a publisher? 3.What is a repository? 4.Relationship between images, packages, publisher and repository? I have definitions for the above in the glossary and within the document. More details and the interrelations between each of them would be welcome. I will work on rearranging some of the sections as you have suggested. Let me know if you have any questions. Thanks again, Jyothi -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/docs-discuss/attachments/20090414/96914ac9/attachment.html>
