Hi Rainer,
Thanks again for your feedback. You've raised many good points and good
questions. See my replies inline. I've preceded them with [AT].
I, too, hope that others can find the time to comment on the changes. The more
the merrier, and the more the better the result. :-)
I'm curious: Do you pronounce your name as "rain" (as in rain that falls from
clouds) then "er"?
Alysson
Rainer Heilke wrote On 01/23/07 23:19,:
>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. ;-)
[AT] Yes, please only look at the changes. Your assumption is correct.
>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).
[AT] This one is actually a tools issue. The tables in this chapter are tagged
in examples because they are examples of tables. So, they show up under
Examples on p. 7. It's not something I have control over.
>p. 16 I wonder if there's a better explanantion of noun phrases, as all
>example items actually contain a verb (Check, Ensure, etc.).
[AT] Actually, the noun phrase concerns the list introduction only ("Legal
requirements checklist:"), not the actual list entries.
>I like changing the list "entries" to "items". I'm hoping that will make it
>easier to translate the Guide.
[AT] For consistency's sake, I'm big on using one term for the same thing,
whenever possible. That's one of the most common issues I see in the
documentation I edit. Our style guide might as well be consistent, too. :-)
>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.
[AT] I just did a Google search and it looks like "low vision" is the correct
term to use. For example, Lighthouse International even defines the term. Check
out: http://www.lighthouse.org/low_vision_defined.htm.
>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.
[AT] Hopefully, it will fix itself, but it might not. One thing I can do before
publishing the final version for this update is a manual pagination to find and
fix such problems. Ideally, the tool would do perfect pagination, but sometimes
it's just not possible.
>p. 26 I would have never seen the incorrect postal code...
[AT] I don't think anyone noticed it for at least several years. :-)
>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.
[AT] It's not that we're discouraging the use of code boxes. Rather, we're not
making a recommendation one way or the other. At Sun, we've typically found
that whether code boxes appear is tools dependent, not so much up to the
writer's discretion.
>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.
[AT] You're right. It is just noting that the text is no longer bulleted but
part of the text above. I wrested with whether to change track such changes and
decided to change track everything (except for things that can't be seen easily
in PDF, such as changing an em dash to a hyphen).
>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. :-)
[AT] Here's the rationale from the person who was mainly responsible for
updating the illustrations content for the Sun style guide: The 2-D action
sequence is actually an animation. It's when you draw two line drawings next to
each other, and draw an arrow that indicates something moved. So, the term "2-D
action sequence" is obsolete and can be replaced by "animation."
>Can I assume the index just automagically reflects the changes in the rest of
>the document (chapter)?
[AT] I wish it were automagic. :-) I did have to manually make the index
changes to reflect the changed content, and I'm making a bunch of refinements
along the way. That said, you don't need to spend time reviewing the index. I'm
being fairly neurotic about checking the changes, so don't feel obliged to
check them yourself. Your comments on the content itself are invaluable.
>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!
[AT] Thank you!
>
>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
[AT] FYI: I'll be vacationing in Florida next week. I was hoping to get the
next chapters out for review before I go, but I've run into a technical glitch
and I'm seeking support from our tools staff. If I don't get the chapter out
this week, then I hope to the week of February 5.
This message posted from opensolaris.org
