Ben, Thanks for these edits - they're very helpful! I'm adding a new section at the beginning to explain more what a boot environment is and how they are useful. I'm also breaking the book into chapters as you suggest. And, revising "enhanced..." comments and removing repetitive instructions to become root user...
I think the revised book will be greatly improved. Due to time crunch, I won't have time for another review cycle, but the finished doc should be much better looking. Barbara On 10/13/08 23:15, Ben Rockwood wrote: > The following pertains only to "Managing Multiple Boot..." > > Barbara.Lundquist at Sun.COM wrote: > >> 2) Managing Multiple Boot Environments in OpenSolaris 2008.11 at >> http://www.opensolaris.org/os/project/caiman/files/snapupgrade.pdf >> >> Changes in Managing Multiple Boot Environments in OpenSolaris 2008.11: >> - This is the former Snap Upgrade chapter with new section >> added for zones support. >> - Upgrade section was moved out of here and into the >> Getting Started Guide. >> - Minimal changes except for new zones support section. >> >> > > > The content is good, but the feel is wrong. > > Similar to "Getting Started.." it should not be a single chapter > document. It needs to be split into the classic "short guide" chapter > format... Intro, Essentials, Advanced1, Advanced2.... For instance, I > have years of experience with LiveUpgrade BE's but I'm feeling confused > and overwhelmed by the book. > > Firstly, there is no clear and direct explanation for what BE's are or > why you want them. Rather, you have to read through and just pick it up > here and there as you go. IMHO, the first page and hense the first > chapter need to convince them that this is something they should care > about and indeed fully understand. > > As is, comments follow: > > * "Advantages of the beadm Utility"; this suggests that this is the > _better_ way, better than what? A better title might be "Features of > the beadm Utility" > * Any 2 step procedure, where step 1 is "Become root", is needlessly > complicated. A bulleted list of subcommands would be more concise and > clear. > * The content regarding zones should be a chapter (Advanced1) and the > 'beadm Command Reference' should be Appendix A. > > Even as an advanced user, I'm not sold on BE's... why would I want > multiple boot environments, why would I go to this trouble? There are a > lot of procedures here, doesn't seem worth the hassle. An introductory > chapter is required. > > > A closing general comment; throughout many of the documents (not just > these we're reviewing) there are phrases and suggestions that something > is "new" or "better" or "improved".... but the userbase is new. There > is no official ties back to Solaris10 and even OpenSolaris 2008.5 is > still really new. I think its best to think of every reader as brand > new. > > Let me beat on that point just a bit... the vast majority of all users > are either coming from Solaris8 or Linux, there are some from Solaris10, > but those moving from SX or 2008.5 are really tiny and likely aren't > reading the docs anyway. Even experienced users are aware that > OpenSolaris (Indiana) is radically different and decide not to trust > their existing Solaris knowledge. Assume the readers are cold, wet, > confused and need to quickly navigate through the document. > > benr. > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/docs-discuss/attachments/20081021/8358306f/attachment.html>
