[jitsi-dev] Add short how-to text to 'Add Contact' dialog?


#1

Hi,

Recently, I was setting up Jitsi with people that aren't used to chat
applications. We are using XMPP and adding contacts seemed to confuse
them slightly: Since they were not really familiar with what an XMPP ID
or name is, they couldn't make much sense of the field "ID or Number"
and didn't know where to put my ID.

It is not that I didn't explain beforehand that the email like address
they got, is there XMPP ID. They just couldn't link the field with this
fact.

Therefore, I hope for a small enhancement of this dialog by adding a
very short explanative text to the top or bottom of it to to explain
what the four fields mean and what a user is supposed to put in there.
This is, I think, done in Skype as well. Alternatively or additionally,
one could also add tool tips to those fields or add a 'help' button. For
a general text I think about something like this:

    Please select one of your accounts to link the new contact to.
    Optionally, you can add the new contact to a new or existing group.
    The number, ID or address is what actually represents your contact
    and belongs into the third field. You can optionally choose to give
    it another name to make it easier to read.

Ideally, this information would be general without a selected account
and would refer to a particular protocol/account type as soon one is
selected. However, I am not sure about this, because it might be
overkill and too confusing if the text would change.

Do you think, something like this would enhance the dialog and make it
even more user friendly? If yes, I could come up with a small patch and
provide a pull request on github if wanted.

Cheers,
Tom


#2

Tom,

Thank you for raising this issue. I distinctly remember stumbling on
this dialog for the first time (almost a year ago for me). Even today, I
find the dialog mildly annoying. The "Add Contact" dialog should be as
pleasant as meeting a new friend :slight_smile:

I propose the following order and labels:

Name:
[Tooltip: "Add a name for this contact"]
[Auto-fill text: "Add name"]
[Cursor should be ready to type in this dialog]

IM address or Phone number:
[Tooltip: "Add either an IM address (such as johnsmith@jit.si ) or a
phone number"]
[Auto-fill text: "johnsmith@jit.si"]

Select account:
[Tooltip: "Which account do you want to use to communicate with this
contact?"]

Select group:
[Tooltip: "Which group do you want to display this contact under?"]

Here's my rational and additional details:

1. Start with the name. Almost every contact manager does this (take a
look at email, address books (even paper address books), IM clients,
etc.) This way the user starts with what they know.

2. Simplify the label "Display name" to "Name". "Display Name" is
unnecessary technical terminology, and since there is no other Name
fields in the dialog, the technical distinction is unnecessary. In
really life no one introduces himself as "Hi, my full name is Joseph
Bloggs, but I go by the display name, Joe." They just say, "Hi, my name
is Joe Bloggs."

3. The "ID or Number" needs renaming. "Number" should become "Phone
number" for clarity. The best terminology for "ID" is less clear.
Currently I favor "IM address".

4a. When possible "Select account" should automatically select a
matching account. For example if the domain in the IM address
("johnsmith@jit.si") matches one of your accounts ("joebloggs@jit.si
(Jabber)"), then Jitsi should auto select. Eventually add more
sophisticated algorithms to grey out incompatible accounts.

4b. Alternatively just select the account that was previously selected.
For most users this will be right most of the time (and for single
account users, it is right every time!) First time users often add
several contacts in a row and will appreciate not having to click and
select this menu every time.

5. "Select group" should be last in the dialog since it is optional.

For further commentary see my responses to your email below.

David

...
Therefore, I hope for a small enhancement of this dialog by adding a
very short explanative text to the top or bottom of it to to explain
what the four fields mean and what a user is supposed to put in there.
This is, I think, done in Skype as well. Alternatively or additionally,
one could also add tool tips to those fields or add a 'help' button.

If you take a look at Skype you'll notice it has no explanatory text,
other than labels and auto-fill text. The UI is straight-forward enough
that no explanation is needed.

Lengthy explanatory text in dialogs is tempting (because it is an easy
fix). However it is often better to re-evaluate the existing design,
with an eye to simplifying (rather than expanding) the UI.

For
a general text I think about something like this:

    Please select one of your accounts to link the new contact to.

This explanation is probably still too abstract. For example, what does
it mean to "link the new contact to"? Will a new user understand what
will happen based on the phrase "link the new contact"? The user needs
to understand to things: (1) they are selecting which account they want
to use to send messages to this contact, and (2) they need to use an
account that can send messages to this contact, by matching Protocols,
etc. This explanation probably would work better in the User
Documentation than a dialog, and when possible hidden from the user.

    Optionally, you can add the new contact to a new or existing group.

I'm not sure this description gives the user new knowledge (other than
the word "optional").

    The number, ID or address is what actually represents your contact
    and belongs into the third field.

Do you think "IM address or phone number" is more explanatory?

You can optionally choose to give
    it another name to make it easier to read.

I think "Name" will become self explanatory, especially if it appears
first in the dialog (instead of the middle).

Do you think, something like this would enhance the dialog and make it
even more user friendly? If yes, I could come up with a small patch and
provide a pull request on github if wanted.

I've been helping start the User Documentation, but I'm not much of a
coder. I can't speak on behalf of the dev. team, but I'd welcome your help.

David

···

On 12/10/2013 1:50 PM, Tom Kazimiers wrote:


#3

David,

Thanks for the feedback, I appreciate it.

Thank you for raising this issue. I distinctly remember stumbling on
this dialog for the first time (almost a year ago for me). Even today, I
find the dialog mildly annoying.

Good to hear that this is not just my opinion.

The "Add Contact" dialog should be as pleasant as meeting a new friend :slight_smile:

Nice analogy. :slight_smile:

I propose the following order and labels:

Name:
[Tooltip: "Add a name for this contact"]
[Auto-fill text: "Add name"]
[Cursor should be ready to type in this dialog]

IM address or Phone number:
[Tooltip: "Add either an IM address (such as johnsmith@jit.si ) or a
phone number"]
[Auto-fill text: "johnsmith@jit.si"]

Select account:
[Tooltip: "Which account do you want to use to communicate with this
contact?"]

Select group:
[Tooltip: "Which group do you want to display this contact under?"]

All of them sound very good and easy to understand to me. I think these
changes would solve the issues I was referring to.

Here's my rational and additional details:

1. Start with the name. Almost every contact manager does this (take a
look at email, address books (even paper address books), IM clients,
etc.) This way the user starts with what they know.

Makes sense.

2. Simplify the label "Display name" to "Name". "Display Name" is
unnecessary technical terminology, and since there is no other Name
fields in the dialog, the technical distinction is unnecessary. In
really life no one introduces himself as "Hi, my full name is Joseph
Bloggs, but I go by the display name, Joe." They just say, "Hi, my name
is Joe Bloggs."

Agreed.

3. The "ID or Number" needs renaming. "Number" should become "Phone
number" for clarity. The best terminology for "ID" is less clear.
Currently I favor "IM address".

Yes, as long as everyone understands what 'IM' stands for. However, I
like it better than ID. It is closer to 'e-mail address', something that
most people know.

4a. When possible "Select account" should automatically select a
matching account. For example if the domain in the IM address
("johnsmith@jit.si") matches one of your accounts ("joebloggs@jit.si
(Jabber)"), then Jitsi should auto select. Eventually add more
sophisticated algorithms to grey out incompatible accounts.

4b. Alternatively just select the account that was previously selected.
For most users this will be right most of the time (and for single
account users, it is right every time!) First time users often add
several contacts in a row and will appreciate not having to click and
select this menu every time.

Both would help users and I would love to see either a) or b) in the
dialog. For the sake of simplicity I favor b).

5. "Select group" should be last in the dialog since it is optional.

Agreed.

> Therefore, I hope for a small enhancement of this dialog by adding a
> very short explanative text to the top or bottom of it to to explain
> what the four fields mean and what a user is supposed to put in there.
> This is, I think, done in Skype as well. Alternatively or additionally,
> one could also add tool tips to those fields or add a 'help' button.
If you take a look at Skype you'll notice it has no explanatory text,
other than labels and auto-fill text. The UI is straight-forward enough
that no explanation is needed.

Oh, thanks for correcting me then. I thought I have seen this on an
(apparently old) screen shot.

Lengthy explanatory text in dialogs is tempting (because it is an easy
fix). However it is often better to re-evaluate the existing design,
with an eye to simplifying (rather than expanding) the UI.

Agreed, this makes sens to me.

> For
> a general text I think about something like this:
>
> Please select one of your accounts to link the new contact to.

This explanation is probably still too abstract. For example, what does
it mean to "link the new contact to"? Will a new user understand what
will happen based on the phrase "link the new contact"? The user needs
to understand to things: (1) they are selecting which account they want
to use to send messages to this contact, and (2) they need to use an
account that can send messages to this contact, by matching Protocols,
etc. This explanation probably would work better in the User
Documentation than a dialog, and when possible hidden from the user.

Indeed, when having those two things in mind, my explanation doesn't
help the user very much. The dialog should avoid technical detail when
possible and leave this to the documentation.

> Optionally, you can add the new contact to a new or existing group.

I'm not sure this description gives the user new knowledge (other than
the word "optional").

Agreed. Although, a user might be interested in knowing which options
(s)he has to add and which are optional.

> The number, ID or address is what actually represents your contact
> and belongs into the third field.

Do you think "IM address or phone number" is more explanatory?

Yes. As long as users know that IM stands for 'instant messenger'. Can
we expect that?

> You can optionally choose to give
> it another name to make it easier to read.

I think "Name" will become self explanatory, especially if it appears
first in the dialog (instead of the middle).

Probably. However, we need to make sure a user doesn't confuse it with
the 'IM address or phone number' field.

> Do you think, something like this would enhance the dialog and make it
> even more user friendly? If yes, I could come up with a small patch and
> provide a pull request on github if wanted.
>
I've been helping start the User Documentation, but I'm not much of a
coder. I can't speak on behalf of the dev. team, but I'd welcome your help.

I will try and add your proposed changes to the dialog and make these
changes a pull request on github (there is not very much change needed,
IMHO). I guess this will clarify, if the developers are interested in
this change.

Regards,
Tom

···

On Wed, Dec 11, 2013 at 01:23:25AM -0600, David Bolton wrote:

On 12/10/2013 1:50 PM, Tom Kazimiers wrote:


#4

3. The "ID or Number" needs renaming. "Number" should become "Phone
number" for clarity. The best terminology for "ID" is less clear.
Currently I favor "IM address".

Yes, as long as everyone understands what 'IM' stands for. However, I
like it better than ID. It is closer to 'e-mail address', something that
most people know.

I'm open to suggestions. I was trying to mimic the terminology of
"e-mail address", since they look the same. Maybe expand the
abbreviation in the Tooltip?

I'm not sure this description gives the user new knowledge (other than
the word "optional").

Agreed. Although, a user might be interested in knowing which options
(s)he has to add and which are optional.

I'd be OK with adding "(optional)" to the end of the tooltip (or
something similar).

    The number, ID or address is what actually represents your contact
    and belongs into the third field.

Do you think "IM address or phone number" is more explanatory?

Yes. As long as users know that IM stands for 'instant messenger'. Can
we expect that?

I'm open to suggestions on the exact terminology.

Do you think, something like this would enhance the dialog and make it
even more user friendly? If yes, I could come up with a small patch and
provide a pull request on github if wanted.

I've been helping start the User Documentation, but I'm not much of a
coder. I can't speak on behalf of the dev. team, but I'd welcome your help.

I will try and add your proposed changes to the dialog and make these
changes a pull request on github (there is not very much change needed,
IMHO). I guess this will clarify, if the developers are interested in
this change.

Wonderful!

David

···

On 12/11/2013 1:35 PM, Tom Kazimiers wrote:


#5

Maybe "Messaging ID [or address] or VOIP number" might be easier for
new users, as I think VOIP is becoming a quite commonly recognised
term?

I guess ideally to make it even clearer, it would prompt for either
"Messaging ID" or "VOIP number" depending on whether a SIP or XMPP
account is selected but that's probably quite tricky.

Regards
Derek

···

On 12 December 2013 02:23, David Bolton <davidkbolton@gmail.com> wrote:

On 12/11/2013 1:35 PM, Tom Kazimiers wrote:

3. The "ID or Number" needs renaming. "Number" should become "Phone
number" for clarity. The best terminology for "ID" is less clear.
Currently I favor "IM address".

Yes, as long as everyone understands what 'IM' stands for. However, I
like it better than ID. It is closer to 'e-mail address', something that
most people know.

I'm open to suggestions. I was trying to mimic the terminology of
"e-mail address", since they look the same. Maybe expand the
abbreviation in the Tooltip?

I'm not sure this description gives the user new knowledge (other than
the word "optional").

Agreed. Although, a user might be interested in knowing which options
(s)he has to add and which are optional.

I'd be OK with adding "(optional)" to the end of the tooltip (or
something similar).

    The number, ID or address is what actually represents your contact
    and belongs into the third field.

Do you think "IM address or phone number" is more explanatory?

Yes. As long as users know that IM stands for 'instant messenger'. Can
we expect that?

I'm open to suggestions on the exact terminology.


#6

Hi,

>>> Do you think "IM address or phone number" is more explanatory?
>> Yes. As long as users know that IM stands for 'instant messenger'. Can
>> we expect that?
> I'm open to suggestions on the exact terminology.

Maybe "Messaging ID [or address] or VOIP number" might be easier for
new users, as I think VOIP is becoming a quite commonly recognised
term?

I guess ideally to make it even clearer, it would prompt for either
"Messaging ID" or "VOIP number" depending on whether a SIP or XMPP
account is selected but that's probably quite tricky.

I just added a pull request which implements most of the discussed
things. There I used "IM address or VoIP number", because it was shorter
than your alternative, gets explained in the tool tip and using
abbreviations for both contact types is somewhat symmetric. :wink:

I didn't touch graying-out of account options based on the contact type
or any account-dependant label changes. However, in my opinion the
changes made improve the dialog quite a bit already. I've added a
screen-shot there:

    https://github.com/jitsi/jitsi/pull/13

Cheers,
Tom

···

On Thu, Dec 12, 2013 at 04:10:01AM +0000, Derek Moss wrote:


#7

Tom,

Thanks for this! Your changes work great for me.

I made some minor suggestions on the pull request.
https://github.com/jitsi/jitsi/pull/13

David


#8

Thanks Tom, I think it works well the way you've done it and actually
IM is probably as well understood as VOIP (or easy enough for people
to understand and remember even if they're not already familiar with
the term IM/Instant Messaging) and it makes sense to stick with
standard terms where possible.

Regards
Derek

···

On 12 December 2013 05:45, Tom Kazimiers <tom@voodoo-arts.net> wrote:

Hi,

On Thu, Dec 12, 2013 at 04:10:01AM +0000, Derek Moss wrote:

>>> Do you think "IM address or phone number" is more explanatory?
>> Yes. As long as users know that IM stands for 'instant messenger'. Can
>> we expect that?
> I'm open to suggestions on the exact terminology.

Maybe "Messaging ID [or address] or VOIP number" might be easier for
new users, as I think VOIP is becoming a quite commonly recognised
term?

I guess ideally to make it even clearer, it would prompt for either
"Messaging ID" or "VOIP number" depending on whether a SIP or XMPP
account is selected but that's probably quite tricky.

I just added a pull request which implements most of the discussed
things. There I used "IM address or VoIP number", because it was shorter
than your alternative, gets explained in the tool tip and using
abbreviations for both contact types is somewhat symmetric. :wink:

I didn't touch graying-out of account options based on the contact type
or any account-dependant label changes. However, in my opinion the
changes made improve the dialog quite a bit already. I've added a
screen-shot there:

    https://github.com/jitsi/jitsi/pull/13

Cheers,
Tom