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.
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.
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?
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)
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.
p. 11 Fourth item at top, the comma after tasks is not strictly
necessary. (I tend to "over-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.
p. 29 bottom. Should that be "imperative tense"? "mood" doesn't seem
quite right.
Index:
p. 37 "procedure headings and" is an orphanh, if you delete "colon (:)"
p. 37 I assume the Big Blank Space under "D" is a place-holder for other
chapters. :-)
p. 38 Under headings, i would suggest removing the "for" in "for
procedures with multiple interfaces."
p. 39 "using in procedures" is an orphan if you remove "screen captures"
Wow, I had to really hunt for those 9 items. ;-) Great work!
If you want any clarification, please ask.
Rainer
