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?
See my replies inline.
Cheers,
Alysson
Rainer Heilke wrote:
>Greetings.
>
>I hope this starts a new thread for this subject, as the old one was
>getting a bit long in the tooth and obfuscated. :-) However, I had to do
>this as an email, as the web interface would not allow me to do the
>indenting I needed below. I hope it shows up correctly this way.
>
>Great work! I like the restructuring, and some good changes were made.
[AT] Thanks. I'm glad you like the changes. :-)
>I have a couple general comments before the specifics.
>
>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.
>Second, indenting. I always like to see clear indenting. Just a personal
>thing that makes it easier for me when scanning/reading a document. Page
>36 is a very good, clear example. On the other hand, page 27 has two
>examples of indenting that I tend to find more difficult. At the top,
>the two glyphs line up with the number 1. I think they should be
>indented, and then the a, b, c lined up with the text of the indented
>glyphs the way they are. So,
>
>1. Determine blah blah blah
> * If no, go ...
> * If yes:
> a. Gently, gently...
> b. Slippy slidey...
> c. And so on...
>
>At the bottom of the page, another format I prefer is:
>
>1. Blah blah
>2. Yadda yadda
>3. This text is so long that
> it wraps around to the next line.
>
> This is a comment regarding the above.
>
>Similarly on p. 14, I would suggest lining up the options (rmdisk0,
>cdrom0, etc.) with "eject", rather than with the $.
>
>Does that make sense? It may seem like a quibble, but when my eyes are
>tired, it makes a big difference. When we consider people with eysight
>issues...
>
>I don't know how much work this would be to change; depends upon the
>tool, I guess. What do you think?
[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.
>And so, on to specifics, of which there are very few:
>
>p. 10 Task. Second line, A task can also include... ("also can" seems
>awkward)
[AT] Okay. I'll change that.
>p. 11 API and CLI should have their abbreviations shown (consistency
>with GUI). API is used on p. 12, and then you can also drop the long
>form of API on p. 17.
[AT] Will do.
>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.
>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?
>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."
>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.
>p. 37 I assume the Big Blank Space under "D" is a place-holder for other
>chapters. :-)
[AT] Yep. :-)
>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.
>p. 39 "using in procedures" is an orphan if you remove "screen captures"
[AT] There's that change-tracking quirk again...
>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.
This message posted from opensolaris.org
