> Hi Rainer,
>
> Thanks again for your feedback.
Hey, I'm glad I was finally able to get to it! :-)
> I'm curious: Do you pronounce your name as "rain" (as
> in rain that falls from clouds) then "er"?
Nope. The first syllable is like the Rhine River, then ther 'er'. As in, "It's
the Rhine, er, I think." ;-) Think of the German poet Rainer Maria Rilke, if
it helps. Most non-germans get it wrong, so I don't take offense until I've
corrected someone a dozen times. ;-) My twisted sense of humour also helps!
> [AT] Yes, please only look at the changes. Your
> assumption is correct.
Good, I hope I didn't miss anything, then.
> >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.
Ah, OK. No worries, then. Just thought I'd ask. And, I'm sure putting them
manually in the Tables list would break something else, because that's how
these tool chains seem to work. :-/ Better to not muck with it (and the
Examples section seems like the more appropriate place of the two, anyway).
> >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.
Mmm, OK. I may need to re-read that, as this was not clear to me. It was
probably me, and not the writing.
> >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. :-)
Agreed. If it also helps with translations and things, we'll take that as a
bonus. :-)
> >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.
Rats, that's too bad. I'm worried that it may cause translation issues, or even
readability issues for people with poor English skills. I'm not disagreeing
with you; it seems to be the correct term, so use it. Perhaps the people that
originally defined the term weren't thinking of these other issues. Maybe it
just sounded more "PC".
> >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.
It's always hard to double-check these things as revisions are made. The best
we can do is to just do our best, so to speak. :-) Various tool chains'
differing constraints also wreck havoc on our best attempt to beat them into
our molds.
> >p. 26 I would have never seen the incorrect postal
> code...
>
> [AT] I don't think anyone noticed it for at least
> several years. :-)
Thanks. It makes me feel better. :-)
> >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.
I see. That makes sense. For me, the question arose out of seeing it there and
then deleted. New readers won't have that historical perspective, so the fact
it's gone will be irrelevant to them.
> >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).
Ah, good. My brain was functioning well at the time, then. ;-)
> >So, we aren't going to cover 2-D action sequences?
>
> [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."
Ok, makes sense.
> >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.
OK, I'll skip the Indexes. I wish (for your sake) that they were automagic.
That would make life a lot easier for you. It may prove valuable (for you to
have others like me) to go through the index itself when we've done all of the
chapter segments, and you're testing the first fully-stiched-together copy or
two of the whole Guide. Even if you're "neurotic" about it, another few sets of
eyes may help. I'm sure it's like many other tasks where you just can't help
the eyes glazing over. Librarians are actually restricted to scanning shelves
for order for a limited period each time, for this very reason.
> >It looks really good. You are botrh to be commended
<snip>
> hope) more translatable. Well done!
>
> [AT] Thank you!
You're very welcome. You deserve it. And, on behalf of the community, let me
thank you for all your hard work.
> [AT] FYI: I'll be vacationing in Florida next week.
Nice! Florida would be too hot for me, but congrats on the holiday, and enjoy
yourself!
> 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.
Hey, it gets done when it gets done. :-) Maybe by the time you get back, the
tools staff will have it sorted.
Have a good break. :-)
Rainer
This message posted from opensolaris.org
