Hi Rainer, Thanks for taking the time to review the chapters and provide such helpful feedback. See my replies inline.
Alysson Rainer Heilke wrote: >Greetings. > >Well, better late than never... I hope I have all the notes I made flagged >properly. (That makes it sound like there's a gazillion, doesn't it? No >worries, there's just a few. :-) ) [AT] As far as I'm concerned, you were on time. :-) >I decided not to speak to the over-all flow of the reshuffled document. It's >too hard, what with there only being the three disconnected chapters and all >of the deletions, etc. My brain is too tired, other than to say that, reading >your comments, the shuffles make sense. [AT] That's fine. It is hard to follow all the reshuffling, much less comment on it. If you have comments later, feel free to send them along. >So, without further ado (and please ignore my "imperative" phrasing): > >1) List of Tables (p. 9) Table 3-2 should be deleted. (This is probably >automated, and hasn't happened because the table is only crossed out?) [AT] Yep. This is automated. It's an artifact of the change tracking. Alas, I can't do anything with it while change tracking is being used. It will go away in the final document. >2) p. 14 Learn to Improve Your Style - the tense changes from the sentence to >the bullet points. "needed" should be "needs", "expected" should be "expects", >"could" should be "can". [AT] Good catch. It's probably been like that a long time. >3) p. 39 There is a reference (just past half-way down) to Sun documentation. >Sun is unnecessary; they are problematic in any technical documentation. [AT] Agreed. I attempted to remove all such references but obviously missed some. >4) p 41 Similarly, the reference to Sun locales is unnecessary. (I know what >you're saying, but it may be worthwhile to phrase the whole sentence more >generically. The readers will not be writing "Sun" documentation, but >OpenSolaris documentation.) [AT] Agreed. Sun's localization folks made the determination that the terms in the table are difficult to understand in some Sun locales, but I don't think OpenSolaris folks would really care about that either. How about rewording as follows: Original: Avoid the terms in the following table. Localization for Europe and Asia have identified these terms as difficult to understand in some Sun locales. Suggested: Avoid the terms in the following table because they are difficult to understand in some languages. >5) p. 41 I would suggest: "...surrounding context, and the best >alternative..." instead of "your". [AT] Sounds good. >6) p. 43 The second item on the list has an example that doesn't use the >suggested alternative. I think the suggested alternative should be "nearby". I >think "For quick retrieval" is a phrase that typically wouldn't be used (hence >changing the sugg. alt., rather than the example). [AT] Good point. I agree that "for quick retrieval" would not be used often, if at all. I like your solution. >7) p. 43 I would reword the "Set aside" correct example: "...grounded mat >before removing the housing." While I often try to do it myself, taking off a >housing or cover is much harder when you're still putting down your tools. ;-) [AT] Another good point. I must admit that I've never even used a grounding mat. :-) I like your solution here as well. >8) p. 82 I think the "to" is awkward in the example, and would just drop it. >The sentences would then become: "You can require passwords be changed >regularly." It's still a little awkward, but I think less so. I've been away >from serious professional writing for far too long to emphatically say which >is more grammatically correct (and my British-based Canadian English may >differ from American English on the more subtle rules anyway). Perhaps: "You >can require regular changing of passwords."? Or: "You can configure the system >to force the regular changing of passwords."? [AT] The text was revised to remove the subjunctive (per Chapter 2, the section titled "Avoid the Subjunctive"), but I do agree that the revision is awkward. How about the following: Original: Your can require passwords to be changed regularly. (Or, remove the "to" as you suggest) Suggested: You can require users to change passwords regularly. I edit by ear quite a bit, and this sentence sounds the best to my ear. How does it sound to your ear? You've sparked my curiosity about how British-based Canadian English differs from U.S. English. (BTW, a change in the latest style guide update includes replacing "American English" with "U.S. English." We found out that "American English" would technically apply to all of the Americas, but it actually applies only to the U.S.) I confess to being U.S. centric. I need to travel! > And that's all I've been able to find. :-) You've done a really great job. I > wish I could give more effective feedback on how the whole document will flow > with the shuffles; perhaps when I can see more of it (or refer back to the > full doc from last summer) in context. [AT] Again, if you have feedback later, I'd welcome it. It is difficult to get a sense of the whole when there are so many changes and you're seeing just a few chapters. >Thanks for your hard work in moving this document forward. It really is >appreciated. >Rainer [AT] Your welcome, Rainer. I'm happy to march forward. This message posted from opensolaris.org
