Re: [Dragora-users] dragora-installer: Message improvement proposal I

[Michael Siegel]

Hi Matías.

Am 26.12.19 um 00:06 schrieb Matias Fonzo:
> Hi Michael,
> 
> Sorry for the delay.

No need to apologize. I knew there would be a bit of a delay.

> I've uploaded a new package for the dragora-installer[1] with the new
> messages and modifications, let me know what you think.
> 
> [1]
> http://rsync.dragora.org/current/packages/x86_64/tools/dragora-installer-20191225-x86_64+1.tlz

I see. I thought we would simply discuss the old installer dialog by
dialog and you'd prepare a new package when that is done. As that is
easier for me, I'll stick to that scheme here, but using the updated
installer as the basis for my comments. So, this message will only
contain issues I found with the first dialog of the updated installer.

All in all, this looks quite a bit better than the previous version.

But:

## I

The window is missing the usual frame.

## II

The second line should just be ended with a single period, not “...”.
(It's a full sentence.)

## III

“Use the arrow keys […] to move through the installer's menus.”

The problem with putting it this way is that it suggests you could
browse through all dialog windows just by using the arrow keys. But
that's not the case.

So, this sentence should rather read:

“Use the cursor keys to move around in the installer's menus.”

Let me provide a rationale for what I did here:

# 1

“move through” -> “move around in” should be clear

# 2

“arrow keys” -> “cursor keys”

I think that “cursor keys” is the adequate term here, for the following
reasons (Bear with me.): First, there are quite some other keys on a
standard keyboard that might be labeled with nothing but arrows. On my
keyboard, these are Backspace, Return, Tab, Shift and Caps Lock. Second,
„cursor keys“ would also include the Home/Pos1 and End keys as well as
Page Up and Page Down, which are not or not necessarily labeled with
arrows, but work as expected in the installer (I've just tested this.).
Third, you can generally use other keys than the “arrow keys” for doing
the same thing, notably 8, 6, 2 and 4 from the numeric keypad. I haven't
been able to verify this actually works in Dragora's installer (keyboard
lacks numpad…), but it should.

# 3

I would omit the visualization of the cursor keys from the sentence. The
current form wouldn't be adequate anyway (see # 2 above). If someone
really shouldn't know what cursor keys are, Wikipedia or a simple web
search will reveal that instantly.

## IV

“The confirmation options in the menus are made with [SPACE] or [ENTER].”

This means something quite different than what you're trying to express.
In its current form, this sentence says that “confirmation options” are
objects, like wooden desks, for example, and that the tools to produce
these objects are “[SPACE]” and “[ENTER]”, just like a saw and a hammer
are tools used to produce a wooden desk.

It should instead say something along the lines of “To confirm ‘things’,
hit [SPACE] or [ENTER]”. I can't think of a viable solution right now,
but I'll try some more and let you know when I come up with something
useful.

Apart from that, I'm wondering whether “[SPACE]” and “[ENTER]” is the
right way to refer to those keys. As far as I know, the names of
computer keyboard keys are usually just capitalized and not written all
in caps, e.g., [Space] and [Enter]. Looking at my own keyboard confirms
that.

## V

The last sentence needs a comma after the closing parenthesis.


That's all.

Have a nice day.


--msi

> 
> El 2019-12-09 20:45, Matias Fonzo escribió:
>> Thanks.  I will look into this soon as I can.
>>
>> El 2019-12-04 16:46, Michael Siegel escribió:
>>> Going through Dragora's installer a couple of times, I realized that the
>>> messages could be improved a bit. I have a couple of ideas on how to do
>>> this and want to share them here for discussion.
>>>
>>> I've decided to go about this one thread per message/dialog and also not
>>> start the next thread until the discussion in the current one is done.
>>> This will help to keep everyone's stress level down (including mine).
>>>
>>> So, here's the installer's first message (currently starting on line 132
>>> in the main script):
>>>
>>>> Welcome to dragora-installer.
>>>>
>>>> This program prepares Dragora 3.0 to run on your computer.
>>>>
>>>>  - To set up Dragora now, press ENTER.
>>>>
>>>>  - To quit, press Esc.
>>>>
>>>> Use the arrow keys to move between options and selections, also TAB to
>>>> jump from one option to another.  ENTER to continue, Esc to cancel or
>>>> return to a previous menu, and Ctrl+C to abort the installation at any
>>>> time.
>>>>
>>>> * Here is a representation of the most commonly used keys in a QWERTY
>>>> layout:
>>>>
>>>> [...]
>>>
>>> Some suggestions on how to improve this:
>>>
>>> I.
>>> I would make the second line say “This program will help you install
>>> Dragora 3.0 on your computer.”
>>>
>>> II.
>>> I'd remove the empty line between the two lines starting with a dash.
>>> Then, I'd move those lines to the end of the dialog window because the
>>> user should have read everything that follows before making a decision,
>>> especially if that decision is to use the installer to set up Dragora.
>>>
>>> III.
>>> Now, the paragraph describing the installer's keybindings seems to be a
>>> bit more complicated to get right. The first sentence could be changed
>>> to the following:
>>>
>>> “Use the arrow keys to move between options and selections, Tab to jump
>>> to the next option and Shift+Tab to jump to the previous one.“
>>>
>>> This would, of course, require Shift+Tab to really work that way. But
>>> that is already being worked on anyway.
>>>
>>> Also, I'm unsure if “options” vs. “selections” is clearly
>>> understandable. If ncurses has standard terms for these kinds of things,
>>> it would be better to use those.
>>>
>>> I'm not really sure about the second sentence. The Ctrl+C part should be
>>> a sentence of its own, IMO. E.g.:
>>>
>>> “You can use Ctrl+C to abort the installation at any time.”
>>>
>>> Then, there are a couple of problems with the first part. First of all,
>>> it doesn't actually state what to do with the mentioned keys, i.e., it
>>> doesn't say that you have to press or hit them. I know this is
>>> self-evident, but the verb still needs to be there. Apart from that,
>>> “ENTER to continue, Esc to cancel” begs the questions „To continue
>>> what?“ and „To cancel what?“.
>>>
>>> IV.
>>> I'd remove the leading asterisk from the line saying “* Here is a
>>> representation of the most commonly used keys in a QWERTY layout:”
>>> Also, I think that “representation” is not the right word to describe
>>> what follows. It's more like a map or an overview. There's probably a
>>> canonical term for this. I'd have to look that up.
>>>
>>>
>>> --msi