Greetings. I'm doing this live for the second half, as it would take too long otherwise (writing, then typing my notes). Not that there's a lot (very little, actually--you both did a great job). The changes look really good. I'm just commenting on the changes, on the assumption the unchanged segments have been proofed to death. ;-)
So, let's get straight to the notes: p. 5 The Tables reference page needs to be updated with the example tables further in (pp 26-7). p. 16 I wonder if there's a better explanantion of noun phrases, as all example items actually contain a verb (Check, Ensure, etc.). I like changing the list "entries" to "items". I'm hoping that will make it easier to translate the Guide. p. 23 I know what you mean by "low vision", but is there a better term? I know "poor vision" may not be PC, but it translates better. Just a thought. p. 23-4 The "Incorrect" table example is made awkward by the page turn. Hopefully, that will get fixed as the deleted text is removed. p. 26 I would have never seen the incorrect postal code... p. 28 ff I like altering the source code comments and letting the coder know. Ibid p. 31. :-) Are we discouraging boxed code examples? I donn't disagree with this, but it is (unfortunately) very common. p. 33 It looks like text is being deleted and added at the same time... Or is this just noting that the text is no longer bulleted, and now goes with the rest of the text above? If so, I agree it looks/fits better. So, we aren't going to cover 2-D action sequences? Just out of curiousity, what was the reasoning? I've seen a number of these used, so I'm just wondering. Perhaps it's because they are being considered inappropriate for the type of documents the Guide covers? If so, I can see that. I'll stop rambling now. :-) Can I assume the index just automagically reflects the changes in the rest of the document (chapter)? It looks really good. You are botrh to be commended for the work you've done. I think that the text changes make it cleaner, more professional, and (I hope) more translatable. Well done! So, things are settling down (I _think_), and I hope I can do the next chapters in a more timely manner. (I also hope that it won't be just me... More eyes and opinions make a better document.) Rainer This message posted from opensolaris.org
