Hey. Alysson Troffer wrote:
>Hi Rainer, > >Thanks for your very helpful feedback. I don't think your reply started a new >thread. Maybe I can start a new one when I send the next chapter out for >review? > > No, it didn't. It may be a good idea to start a new thread with the next chapter--this one is getting to the point where people will get lost, I fear. >>First regards examples. There are two types of examples generally, >>in-line and "excerpted." By that I mean that one type of example is >>prefaced by a comment like, "For example," continues directly without an >>Examples number, and does not appear in the examples list. The other >>type is actually pulled out with the example number, and appears in the >>list. In the last review, we sort of went with just dropping the one or >>two examples from the Examples list. Now, I'm wondering if we want to be >>more consistent, and have _all_ examples "excerpted" and listed. I don't >>know, I'm just throwing this out as food for thought. I just found that >>having two types seems a little inconsistent, now that there's a few >>more. But then, excerpting them all could feel clumsy. I don't know. >> >> > >[AT] It does seem a bit inconsistent, but my sense is that it would be too >cumbersome to turn all of the examples into formal examples with captions and >a listing in the List of Examples. I think we have too many examples for that >to work. It would break the flow of the content too much. > >The other possibility would be to turn the four formal examples into informal >examples (what you're calling "excerpts"). However, I'm not so sure. Here are >my thoughts: > >* Example 5-1 shows an example at the end of a procedure. In actual >procedures, I do think a formal example is a good idea when it falls at the >end of the procedure. > >* Example 5-2 provides an example of a task map, which is a nice complement to >the two "formal" task map examples in Chapter 9, "Structuring Information." > >* Example 5-3 and Example 5-4 could possibly go either way (formal or >informal). However, they are examples of continuous prose for API tasks, >which are very different from the other examples in this chapter. So, they do >stand apart and perhaps benefit from being in formal examples. > > Those are good arguments for keeping them the way they are. I was a little unsure whether to even mention this. I didn't really like the "all or nothing" solutions but finally decided to mention it for something to think about. Your explanations make good sense, so if we keep to this model, then _that_ becomes the "consistency." We'll probably always have some that could go either way. (Listen to all this silly "we" stuff. _You're_ the one doing all the heavy lifting, I'm just "along for the ride," as it were.) >>Second, indenting. I always like to see clear indenting. Just a personal >>thing that makes it easier for me when scanning/reading a document. >> >[AT] I do see what you mean (too bad the web interface didn't cooperate!). In >actual docs I've worked with at Sun, this indenting is handled automatically >by the authoring tool. To simulate that in the style guide, it would have to >be done manually, as I'm not using actual tags for procedures and steps. I'm >just using text. So, for example, I'd have to do a hard break at the end of >the line and then add spaces on the next line to make them match up. Making >that change throughout (and it would be in a lot of places) would make >maintaining the text more difficult. > >Despite all that, do you think it's worth fixing? I'm on the fence, but you >could probably nudge me and I'd fall either way. > > Ouch! No, if it's that much work, let's not. Maybe down the road we can use a tool to fix up revision 17 if we want to. It is something that I feel strongly about, but the amount of work isn't worth it, and if it's so manual, then doing it will cause headaches down the road. I've had to clean up text to remove hard CR/LF's in large docs--it sucks. >>p. 11 Fourth item at top, the comma after tasks is not strictly >>necessary. (I tend to "over-comma.") >> >> > >[AT] Personally, I'd leave the comma in. There's a natural pause there that I >think benefits from the use of a comma. > > OK. Like I say, I tend to over-comma, so I am ocassionally too brutal in cleaning up/compensating. >>p. 11 Do we want to add a list item to the user task analysis that >>suggests an analysis of how the tool differs from other, similar >>products? This is often important to the end user, helping them to >>decide early on whether to read the document, or look for a different tool. >> >> > >[AT] This is not something that I've seen done. To me, it seems a bit >precarious, possibly for legal reasons. Could you elaborate more on what >you've seen? Do others have an opinion? > > Yeah, I didn't think of the legal angle. As a specific example, at work we migrated from Solaris 8 to 10. This allowed a migration from MIT Kerberos to SEAM. The problem was that SEAM doesn't (didn't?) include the ksu binary, which we depend upon for passwordless access to group accounts (like, say, "oracle"). In discussing the matter with Sun, the engineers took a while to grasp that RBAC doesn't resolve the ksu issue (nor does sudo, etc.). These sorts of things are often beneficial to know up front, rather than reading a 300+ page document, and then still sitting back and saying, "but it didn't tell me how to address _this_" where _this_ is something the tool isn't designed to address, but you still don't know that. It's just a suggestion, and if added would have to be phrased carefully. >>p. 29 bottom. Should that be "imperative tense"? "mood" doesn't seem >>quite right. >> >> > >[AT] Actually, "imperative mood" is the correct grammar term. Here's a >sentence I got from the Random House Handbook, Third Edition: "English verbs >show certain other changes of form to indicate the mood or manner of a clause." > > Wow, I've never heard it called this in grammatical terms. Maybe I'm showing my age. Isn't "mood" harder to translate, though? >>Index: >>p. 37 "procedure headings and" is an orphanh, if you delete "colon (:)" >> >> > >[AT] This is a change-tracking quirk. The primary entry isn't actually >deleted, even though it is marked as such. > > Thought so, but had to mention it. :-) >>p. 37 I assume the Big Blank Space under "D" is a place-holder for other >>chapters. :-) >> >> > >[AT] Yep. :-) > > <grin> >>p. 38 Under headings, i would suggest removing the "for" in "for >>procedures with multiple interfaces." >> >> > >[AT] My sense is that it's clearer to leave in the "for." It's also used in >the "for hardware procedures" secondary entry. > > OK. :-) >>p. 39 "using in procedures" is an orphan if you remove "screen captures" >> >> > >[AT] There's that change-tracking quirk again... > > Yep. >>Wow, I had to really hunt for those 9 items. ;-) Great work! >> >>If you want any clarification, please ask. >> >>Rainer >> >> > >Thanks again, Rainer! I very much appreciate your eagle eye. > > You're very welcome. I'm glad I was able to help, and on time, too! :-) Rainer
