proposed terminology changes for 0.3.x

[Jeff Fortin]

In my specto-fix-the-damn-strings-and-translations branch, I have begun thinking again on something that has annoyed me for a while now: the terminology, used both in the console/gui and in in the code is confusing. Especially in the code.

The terminology I am referring to is the one of the watch "states", so here is what I am proposing we use instead:

• idle: the watch is not marked as having unread items, and is not doing anything (translator hint synonyms: idle/sleep/ready)
• checking: the watch is busy checking for updates (translator hint synonyms: checking/refreshing). This was previously called "updating".
• changed: the watch has new unread items that have not yet been "cleared" by the user.
• error: the watch encountered an error?

"checking" was previously called "updating", and "changed" was previously called "updated". These previous terms were terribly confusing, because they ended up creating messages where you are not 100% sure if it means the watch has "finished checking" or if it means that it "finished checking and has detected changes". It also made the code much harder to understand, since you're never entirely sure that the ones who wrote it were not drunk that day :)

Here's an example of Crappy Confusion in the 0.2.x series:

console.py:46 msgid "Watch %s is updated!"
console.py:51 msgid "Watch %s started updating."
console.py:53 msgid "Watch %s has finished updating."

When a watch goes through the checking process successfully (status != "error") but does not have new unread items (status != "updated"), do NOT use the wording "updated" or "finished updating" or anything like that, because it induces confusion. Instead, say that the watch is now "idle".

Basically, these are the possible paths a watch can take:

• idle --> checking --> idle.
• idle --> checking --> updated --> [user clears the watch] --> idle.

I would like your thoughts on this if possible. I may even need some help (from wout perhaps) for clarifying certain parts of the code, because even I don't know 110% sure if it really does what it looks like it does. This is why I'm proposing these term changes actually, and if they are accepted, I would suggest that they be enforced for consistency.

[deeesseee]

From a users standpoint (that'd be me) this makes since. My only
question is did you mean to label the 3rd state "Changed" at the top,
but then use "Updated" when you were describing the two different
possibilities?

On Aug 8, 5:36 pm, Jeff Fortin <nekoh...@gmail.com> wrote:
> In my specto-fix-the-damn-strings-and-translations branch, I have begun
> thinking again on something that has annoyed me for a while now: the
> terminology, used both in the console/gui and in in the code is
> confusing. Especially in the code.
>
> The terminology I am referring to is the one of the watch "states", so
> here is what I am proposing we use instead:
>

>       * idle: the watch is not marked as having unread items, and is not

>         doing anything (translator hint synonyms: idle/sleep/ready)

>       * checking: the watch is busy checking for updates (translator

>         hint synonyms: checking/refreshing). This was previously called
>         "updating".

>       * changed: the watch has new unread items that have not yet been
>         "cleared" by the user.
>       * error: the watch encountered an error?

>
> "checking" was previously called "updating", and "changed" was
> previously called "updated". These previous terms were terribly
> confusing, because they ended up creating messages where you are not
> 100% sure if it means the watch has "finished checking" or if it means
> that it "finished checking and has detected changes". It also made the
> code much harder to understand, since you're never entirely sure that
> the ones who wrote it were not drunk that day :)
>
> Here's an example of Crappy Confusion in the 0.2.x series:
>
> console.py:46 msgid "Watch %s is updated!"
> console.py:51 msgid "Watch %s started updating."
> console.py:53 msgid "Watch %s has finished updating."
>
> When a watch goes through the checking process successfully (status !=
> "error") but does not have new unread items (status != "updated"), do
> NOT use the wording "updated" or "finished updating" or anything like
> that, because it induces confusion. Instead, say that the watch is now
> "idle".
>
> Basically, these are the possible paths a watch can take:
>

>       * idle --> checking --> idle.
>       * idle --> checking --> updated --> [user clears the watch] -->

[Jeff Fortin]

From a users standpoint (that'd be me) this makes since

Do you mean "this makes sense"?

did you mean to label the 3rd state "Changed" at the top,
but then use "Updated" when you were describing the two different
possibilities?

Hmm, which "two possibilities"? Not sure I understood correctly, but my general idea here was that the words used were inducing confusion, and that I would change them to words that are very different from each other (idle - checking - changed - error). That means I would "ban" the use of the word "update" and its derivatives :)

[Felipe Sere]

On Sat, Aug 9, 2008 at 12:36 AM, Jeff Fortin <neko...@gmail.com> wrote:
> In my specto-fix-the-damn-strings-and-translations branch, I have begun
> thinking again on something that has annoyed me for a while now: the
> terminology, used both in the console/gui and in in the code is confusing.
> Especially in the code.
>
> The terminology I am referring to is the one of the watch "states", so here
> is what I am proposing we use instead:
>
> idle: the watch is not marked as having unread items, and is not doing
> anything (translator hint synonyms: idle/sleep/ready)
> checking: the watch is busy checking for updates (translator hint synonyms:
> checking/refreshing). This was previously called "updating".
> changed: the watch has new unread items that have not yet been "cleared" by
> the user.
> error: the watch encountered an error?

These changes sound sane to me. I havent used specto in some time
(sorrrrry...), but are these "states" acompanied by a nice symbol in
the traybar?

> "checking" was previously called "updating", and "changed" was previously
> called "updated". These previous terms were terribly confusing, because they
> ended up creating messages where you are not 100% sure if it means the watch
> has "finished checking" or if it means that it "finished checking and has
> detected changes". It also made the code much harder to understand, since
> you're never entirely sure that the ones who wrote it were not drunk that
> day :)
>
> Here's an example of Crappy Confusion in the 0.2.x series:
>
> console.py:46 msgid "Watch %s is updated!"
> console.py:51 msgid "Watch %s started updating."
> console.py:53 msgid "Watch %s has finished updating."

Yup, this is crappy and makes for confusing translations...

> When a watch goes through the checking process successfully (status !=
> "error") but does not have new unread items (status != "updated"), do NOT
> use the wording "updated" or "finished updating" or anything like that,
> because it induces confusion. Instead, say that the watch is now "idle".
>
> Basically, these are the possible paths a watch can take:
>
> idle --> checking --> idle.
> idle --> checking --> updated --> [user clears the watch] --> idle.
>
> I would like your thoughts on this if possible. I may even need some help
> (from wout perhaps) for clarifying certain parts of the code, because even I
> don't know 110% sure if it really does what it looks like it does. This is
> why I'm proposing these term changes actually, and if they are accepted, I
> would suggest that they be enforced for consistency.

Ehm, if you are not a 110% sure of what the code means, and you are
planning to enfoce this terminology, will this lead to a code-rewrite,
to not only clarify the meaning of the "codewords", but also the code itself?

--
Felipe Sere

[deeesseee]

Yes I did mean "this makes sense," my bad.

What I was talking about with the possibilities is near the end of
your post you described the two possible paths that can happen. In the
second path, you used "updated" as the third state, but you had said
at the beginning of your post that you were going to call this state
"changed."

Hope this clarifies.

[Jeff Fortin]

Ehm, if you are not a 110% sure of what the code means, and you are
planning to enfoce this terminology, will this lead to a code-rewrite,
to not only clarify the meaning of the "codewords", but also the code itself?

Nah, I don't think this will need a code rewrite. Just changing some strings around, the hard part being, "making sure that I understand properly what I'm changing and that it really means what I think it means".

In the second path, you used "updated" as the third state, but you had said
at the beginning of your post that you were going to call this state
"changed."

Oops, I guess I must have been tired, or this is a good example of why the previous terminology was confusing :) what I meant was:

• idle --> checking --> idle.

• idle --> checking --> changed --> [user clears the watch] --> idle.

[Jeff Fortin]

Today, I finally made the big terminology changes I had planned. I think both the code and the user interface are much clearer now (especially regarding the watch statuses).

Pushed up to revision 94 on a temporary place, so you can
bzr branch http://code.ecchi.ca/specto-0.3-translatable-strings-fix/

I think it would be good to take it for a spin and test if it causes any bugs (I could not find any so far) before I merge it into specto-main and ask translators to get to work.

P.s.: my French translation is not included in that commit yet, but I do have it here internally for making sure everything is translatable. I'm holding it back until we're in string freeze of some sort.