Feature #11128

Update documentation to match Vidalia removal

Added by intrigeri 2016-02-15 13:03:17 . Updated 2017-03-20 16:44:54 .

Status:
Resolved
Priority:
Normal
Assignee:
Category:
Target version:
Start date:
2016-02-15
Due date:
% Done:

100%

Feature Branch:
feature/6841-replace-vidalia
Type of work:
End-user documentation
Blueprint:

Starter:
Affected tool:
Onion Circuits
Deliverable for:

Description

… and being replaced by Onion Circuits + a custom GNOME Shell extension.


Subtasks


History

#1 Updated by intrigeri 2016-02-18 20:33:50

  • Affected tool changed from Tor Monitor to Onion Circuits

#2 Updated by intrigeri 2016-02-20 10:45:40

  • Status changed from Confirmed to In Progress
  • Assignee set to intrigeri
  • % Done changed from 0 to 10

Started (commit:04c44d3497c6b44087c4b1c51a3c01eb31312615), here is what remains to do: [moved to description].

#3 Updated by intrigeri 2016-02-23 01:41:12

  • Priority changed from Normal to High
  • Target version changed from 2016 to Tails_2.2

#4 Updated by intrigeri 2016-02-23 10:54:01

  • Description updated

#5 Updated by intrigeri 2016-02-27 11:16:43

  • Description updated

#6 Updated by intrigeri 2016-02-27 11:39:01

  • Description updated

#7 Updated by intrigeri 2016-02-27 12:49:51

  • Description updated
  • Assignee changed from intrigeri to anonym
  • % Done changed from 10 to 50
  • QA Check set to Ready for QA

Done, please review’n’merge into testing and devel. This needs to go in before 2.2 is released, so assigning to anonym. Still, it would be nice if doc writers (added as watchers) had a look => if you want it, raise your hand and I guess that anonym will happily reassign to you once he has merged the branch :)

#8 Updated by spriver 2016-02-29 14:24:40

I had a look at the doc changes. I did not find anything to complain about, but maybe someone else could have a quick look at it?
Another question: shall we rewrap lines in .mdwn to 80 lines while writing doc?

#9 Updated by intrigeri 2016-02-29 14:35:46

> I had a look at the doc changes. I did not find anything to complain about, but maybe someone else could have a quick look at it?

Thanks!

> Another question: shall we rewrap lines in .mdwn to 80 lines while writing doc?

I don’t think I want to have this discussion here (== on this ticket).

#10 Updated by anonym 2016-03-06 19:12:03

  • Status changed from In Progress to Fix committed
  • % Done changed from 50 to 100

Applied in changeset commit:227ead1d84a8e2db214d0fd786b1001831294dfe.

#11 Updated by anonym 2016-03-06 19:46:03

  • Assignee deleted (anonym)
  • QA Check changed from Ready for QA to Pass

Looks great to me.

#12 Updated by sajolida 2016-03-07 11:57:09

I want to review this myself as well but the timing around Onion Circuits is 2.2 was very bad for me to work on this before the release; but I’m glad it happened! So I’ll work on this after the release. Let’s just hope we won’t break many translations…

#13 Updated by anonym 2016-03-08 19:02:41

  • Status changed from Fix committed to Resolved

#14 Updated by sajolida 2016-04-22 09:58:30

  • Status changed from Resolved to In Progress
  • Assignee set to intrigeri
  • Priority changed from High to Normal
  • Target version deleted (Tails_2.2)
  • % Done changed from 100 to 60
  • QA Check changed from Pass to Ready for QA

I pushed some improvements in feature/6841-replace-vidalia. Assigning to intrigeri for review as the original author.

#15 Updated by intrigeri 2016-04-29 03:58:36

  • Status changed from In Progress to Resolved
  • Assignee deleted (intrigeri)
  • Target version set to Tails_2.4
  • % Done changed from 60 to 100
  • QA Check changed from Ready for QA to Pass

Merged, great work, thanks! I’m proud you didn’t fully rewrite it ;)

In passing, I’m not 100% convinced by the “Tor is stopped or not started yet” terminology (that replaced “stopped or starting” in a commit that’s about something else), that covers the case when the tor daemon has started but is not ready to use (connected) yet: I understand that from the user’s PoV Tor is not fully started until it’s connected and usable, but this is not consistent with the “Tor is ready” notification, so if you prefer this new terminology, perhaps apply it everywhere? No big deal, of course.

#16 Updated by sajolida 2016-04-30 10:38:46

  • Assignee set to intrigeri
  • QA Check changed from Pass to Info Needed

> Merged, great work, thanks! I’m proud you didn’t fully rewrite it ;)

Yeah, me too actually. It means I can control myself :)

> In passing, I’m not 100% convinced by the “Tor is stopped or not
> started yet” terminology (that replaced “stopped or starting” in a
> commit that’s about something else), that covers the case when the
> tor daemon has started but is not ready to use (connected) yet: I
> understand that from the user’s PoV Tor is not fully started until
> it’s connected and usable, but this is not consistent with the “Tor
> is ready” notification, so if you prefer this new terminology,
> perhaps apply it everywhere? No big deal, of course.

I want to understand your concern better because maybe it reflects that
I don’t understand how Tor is starting…

Why do you mean by ‘this is not consistent with the “Tor is ready”
notification’?

I just tried the following:

1. Unplug my Ethernet cable.
2. Then Tor status goes disconnected (good!)
3. Plug the cable again.
4. Then Tor Launcher appears with the process bar connecting to Tor.
5. Once the bar is full Tor Launcher disappears and Tor status goes
connected and I get the “Tor is ready” notification.

In this scenario the Tor status and the notification are in sync and
translate “Tor is ready” which would be a synonym of “Tor has started”.
Or do you mean we should use the same terminology (“started” = “ready”)
in the documentation and the notification?

What am I missing?

#17 Updated by intrigeri 2016-05-03 10:39:31

  • Assignee changed from intrigeri to sajolida

> I want to understand your concern better because maybe it reflects that I don’t understand how Tor is starting…

OK.

> Why do you mean by ‘this is not consistent with the “Tor is ready” notification’?

The branch I’ve merged makes it sound like Tor gets ready immediately when it was started: it says that the onion icon being crossed-out implies that Tor is stopped, while in practice it is also crossed when Tor is started but not ready yet.

> Or do you mean we should use the same terminology (“started” = “ready”) in the documentation and the notification?

Yes. IMO synonyms (even if they were really good ones) suck when it comes to talking about technical concepts to our target user base.

I’ll try to clarify how I see it.

There are 3 situations:

  • the tor daemon is not running
    • UX: crossed-out onion icon
    • doc before your changes: “stopped or starting”
    • doc after your changes: “Tor is stopped or not started yet”
  • the tor daemon is running, but not connected to the Tor network yet
    • UX: crossed-out onion icon
    • doc before your changes: “stopped or starting”
    • doc after your changes: “Tor is stopped or not started yet” ← this one feels wrong, unless we decide that “ready” == “started”
  • the tor daemon is running and connected to the Tor network
    • UX: non-crossed-out onion icon + “Tor is ready”
    • doc: “connected to Tor”

So, I see three options:

  • either we decide that “ready” "started" “connected to Tor” and use all of those to mean the same thing
    • pro: no change to apply, that’s the status quo
    • cons: we merge different technical concepts together, which 1. leaves us less flexibility if we ever need to convey subtler differences between these different Tor status in the future; 2. can be confusing for people who know a little bit what’s happening behind the curtain, and are keen to understand and learn more
  • or we use only “Tor is ready” and “connected to Tor” to indicate that the tor daemon is connected to the Tor network
    • this implies that we express more precisely what the crossed-out icon means, e.g. with “stopped or starting”, or whatever you prefer
    • pro: we keep the “started” concept aside, don’t introduce it as yet another word in our terminology, and keep it on the side for whenever we need it
  • or we use only “Tor has started” and “connected to Tor” to indicate that the tor daemon is connected to the Tor network
    • pro: conceptually, it’s probably a good simplification, as users might not care that the tor daemon is started if they can’t use it
    • cons: we use the same word to mean two quite different things on the dev side (code, etc.) and on the doc/UX side, which may not ease communication accross teams
    • cons: confusing for users with a little bit more technical background

My prefered option is clearly the 2nd one. I dislike the 1st one quite a bit, but well, you’re the expert. I dislike the 3rd one but could live with it.

#18 Updated by sajolida 2016-05-05 06:17:48

  • Assignee changed from sajolida to intrigeri
  • QA Check changed from Info Needed to Ready for QA

Ok, thanks for the clarification. I went for option 2 and did f1c421f.

The terminology “ready” is not always easy to use as it’s better to translate a change of state (or an event) than the state itself (as in “Tor is ready” for a notification). So I used “connected to Tor” or “not connected to Tor” everywhere instead. Negations are more prone to misreading but here I think that “Tor is disconnected” would be worse actually because it implies that it was connected in the past, which is not true when starting.

Does my new branch solve your concerns?

#19 Updated by intrigeri 2016-05-05 09:07:53

> Does my new branch solve your concerns?

Absolutely! I’ll now build and likely merge.

#20 Updated by intrigeri 2017-03-20 16:44:54

  • Assignee deleted (intrigeri)
  • QA Check changed from Ready for QA to Pass