Hello tbb-devs. Here are a few divergent thoughts on presenting the Tor Browser manual in a sensible manner for Tor Browser users. Please provide feedback regarding whether any of these seem reasonable/feasible.
&&&&&&
0) Include a pdf file in an easy to locate place in the Tor Browser directory.
Con: As discussed a couble IRC meetings ago, the major obstacle here is that most Mac users do not know how to turn their Tor Browser app into a directory, and so they would never see it. Not so good.
1) Replace the help desk email label in tor-launcher with a button, which, when clicked, tells the user's system to open a local pdf file with the system's default pdf viewer.
A con to this approach is that I don't know if it is even possible at all; that is, I'm not sure if JS is capable of detecting what the default application for a filetype is or, if it's not, I'm not sure it's capable of just "opening a file" that needs to be opened with a specific, local application.
2) The same as 1) but ship evince with Tor Browser and onClick, open a pdf file with something like an `evince tb-manual.pdf` command.
A con to this approach would be that this might not work at all for various non-Gnome GNU/Linux users. Also the Tor Browser is that much bigger.
3) Replace the help desk email label in tor-launcher with a button, which, when clicked, opens a XUL window (like window.open) that contains nothing but an iFrame which loads the the local index.html file (from which the user can then navigate to all the other html pages because of the manual's design)
con: ??.
This seems like a pretty possible thing to do right now. Is it? I could not actually get my implementation of this idea even close to working, but I also introduced a lot of new moving parts at once, and I'm still getting the hang of debugging. This seems like it would be the most user-friendly workflow of these various approaches.
4) Make the Tor Browser manual prominently available for download on the Tor Browser download page as a pdf.
cons: Now users have two things to verify to make sure they didn't just download malware. Who's really going to do that for a pdf file, anyway? I think most users are quite used to a download being one thing, and not two (or three). I'm not sure it's reasonable to expect that all users will download a separate manual. This is not a great workflow. Users could just open the pdf file in the browser they used to download Tor Browser, though.
5) Direct users to https://tb-manual.torproject.org/, which weasel just set up. This could either be done from the download page or a non-wired link in tor-launcher.
cons: I think fewer users would actually see the manual this way, and this distribution method would probably be less effective at reducing load on the help desk for similar reasons to 4). We've had the the Short User Manual on our web infrastructure for some time and most users do not know it exists. Although maybe that was an advertising problem?
******
I'm not a huge fan of 4) or 5), as they don't actually solve the problem of distributing a manual with Tor Browser. I've included them for completeness, nonetheless.
Also there are probably ways of getting the tor browser manual in the hands of users that I'm not thinking of. Any other ideas? Do you like any of the above ideas?
The relevant ticket here is https://trac.torproject.org/projects/tor/ticket/11698
Roger Dingledine:
On Wed, May 28, 2014 at 02:47:34AM +0000, Matt Pagan wrote:
- The same as 1) but ship evince with Tor Browser and onClick, open a
pdf file with something like an `evince tb-manual.pdf` command.
Doesn't TBB come with an in-tab javascript pdf reader these days?
--Roger
I think it would be quite helpful for users if it were still possible to read the Tor Browser manual in the event that Tor or Tor Browser fails prior to the point where users have a tab open.
Maybe there is a way to utilize PDF.js to read the manual before (or regardless of whether or not) Tor bootstraps. That would be way cool!
Also I thought of what my question marks on 3) should be. It would not be so cool if it were reasonably possible for tor-launcher to fail such that Tor Browser users could not access/read the manual that is supposed to help them.
Matt Pagan:
- Include a pdf file in an easy to locate place in the Tor Browser
directory.
- Replace the help desk email label in tor-launcher with a button,
which, when clicked, tells the user's system to open a local pdf file with the system's default pdf viewer. 2) The same as 1) but ship evince with Tor Browser and onClick, open a pdf file with something like an `evince tb-manual.pdf` command. 4) Make the Tor Browser manual prominently available for download on the Tor Browser download page as a pdf.
I am still unconvinced that PDF is an interesting format for what we want to achieve.
- Direct users to https://tb-manual.torproject.org/, which weasel just
set up. This could either be done from the download page or a non-wired link in tor-launcher.
No. We need to ship a manual with the browser so users have a reference on how to configure bridges.
Lunar:
I am still unconvinced that PDF is an interesting format for what we want to achieve.
This may not change your mind, but I wanted to point out to you that a pdf file created with wkhtmltopdf (the wk is for webkit) would preserve the interactivity of any svg files that are contained therein, (e.g. the interactive svg file you made specifically for the manual).
Matt Pagan:
Lunar:
I am still unconvinced that PDF is an interesting format for what we want to achieve.
This may not change your mind, but I wanted to point out to you that a pdf file created with wkhtmltopdf (the wk is for webkit) would preserve the interactivity of any svg files that are contained therein, (e.g. the interactive svg file you made specifically for the manual).
A PDF does not reflow its text content according to the display size. So if you have a small screen or wish bigger fonts, you have to spend all your time scrolling. It's harder to change the text colors (think about visually impaired users). I don't know about text-to-speech with wkhtmltopdf but most solutions are working fine with web browsers.
PDF are great when you print. For online uses, really, nope (unless you want the feeling of a book — but we are not doing a book).
Lunar:
Matt Pagan:
Lunar:
I am still unconvinced that PDF is an interesting format for what we want to achieve.
This may not change your mind, but I wanted to point out to you that a pdf file created with wkhtmltopdf (the wk is for webkit) would preserve the interactivity of any svg files that are contained therein, (e.g. the interactive svg file you made specifically for the manual).
A PDF does not reflow its text content according to the display size. So if you have a small screen or wish bigger fonts, you have to spend all your time scrolling.
No more so than one would with any other pdf document. The format is pretty widely used. IMO, users' likely previous familiarity with this format is an advantage.
It's harder to change the text colors (think
about visually impaired users).
I'd like to point out that visually impaired users can inverse the colors in a pdf document if they wish, usually with Ctrl-I or the equivalent.
I don't know about text-to-speech with wkhtmltopdf but most solutions are working fine with web browsers.
wkhtmltopdf uses the WebKit rendering engine to display web content, which is what Chrome and the Android Web browser use. Content is rendered the same way as it is in those browsers. The text-to-speech capabilities are the same is in Google Chrome.
PDF are great when you print. For online uses, really, nope (unless you want the feeling of a book — but we are not doing a book).
I got the impression I was working on something book-like. I'm familiar with other user manuals being either books or pdf documents.
Matt Pagan:
PDF are great when you print. For online uses, really, nope (unless you want the feeling of a book — but we are not doing a book).
I got the impression I was working on something book-like. I'm familiar with other user manuals being either books or pdf documents.
In my mind, we are creating an online help manual. Look at what happen when you open Firefox (or Tor Browser for the time being) Preferences and click on the Help button. Look also what the index look like when you go to Help in the Help menu.
The various screens of the wizard and the Network Preferences panel should have similar Help button. We need to have an index as well, but it's easy to combine both approaches with Mallard.
What we care about that needs to be read out of the Tor Browser:
* How to circumvent censorship * Troubleshooting when Tor Browser does not start * How to get more support
Have I missed anything? In any cases, it's a small subset of the manual.
But sure, you can read an online help manual cover-to-cover. It's actually what I did with every house appliances since I was a kid. But I don't believe most people do that.
On 5/27/14 10:47 PM, Matt Pagan wrote:
...
- Replace the help desk email label in tor-launcher with a button,
which, when clicked, tells the user's system to open a local pdf file with the system's default pdf viewer.
A con to this approach is that I don't know if it is even possible at all; that is, I'm not sure if JS is capable of detecting what the default application for a filetype is or, if it's not, I'm not sure it's capable of just "opening a file" that needs to be opened with a specific, local application.
There are APIs inside Firefox for opening local files and "revealing" directories/folders. It should be fairly easy to implement this option.
- Replace the help desk email label in tor-launcher with a button,
which, when clicked, opens a XUL window (like window.open) that contains nothing but an iFrame which loads the the local index.html file (from which the user can then navigate to all the other html pages because of the manual's design)
con: ??.
This seems like a pretty possible thing to do right now. Is it? I could not actually get my implementation of this idea even close to working, but I also introduced a lot of new moving parts at once, and I'm still getting the hang of debugging. This seems like it would be the most user-friendly workflow of these various approaches.
I agree this would be the most user friendly option. It will also require the most implementation effort. Basically, we need to build a XUL+HTML (or XUL+PDF) help viewer that does not allow users to "escape" and start accessing the network.
- Make the Tor Browser manual prominently available for download on the
Tor Browser download page as a pdf.
cons: Now users have two things to verify to make sure they didn't just download malware. Who's really going to do that for a pdf file, anyway? I think most users are quite used to a download being one thing, and not two (or three). I'm not sure it's reasonable to expect that all users will download a separate manual. This is not a great workflow. Users could just open the pdf file in the browser they used to download Tor Browser, though.
Option 4 would probably meet the needs of many users (as would option 5). If they are downloading our software from torproject.org they will probably expect the manual to be available online as well. But for some users, bundling the manual with the browser is essential for safety.
- Direct users to https://tb-manual.torproject.org/, which weasel just
set up. This could either be done from the download page or a non-wired link in tor-launcher. ...
The same comments that I made regarding option 4 apply to this one: good to do, but it won't solve the entire problem. Providing a downloadable PDF (option 4) gives people more flexibility but maybe the presentation of the manual is better at https://tb-manual.torproject.org/.
Mark Smith:
On 5/27/14 10:47 PM, Matt Pagan wrote:
...
- Replace the help desk email label in tor-launcher with a button,
which, when clicked, tells the user's system to open a local pdf file with the system's default pdf viewer.
A con to this approach is that I don't know if it is even possible at all; that is, I'm not sure if JS is capable of detecting what the default application for a filetype is or, if it's not, I'm not sure it's capable of just "opening a file" that needs to be opened with a specific, local application.
There are APIs inside Firefox for opening local files and "revealing" directories/folders. It should be fairly easy to implement this option.
- Replace the help desk email label in tor-launcher with a button,
which, when clicked, opens a XUL window (like window.open) that contains nothing but an iFrame which loads the the local index.html file (from which the user can then navigate to all the other html pages because of the manual's design)
con: ??.
This seems like a pretty possible thing to do right now. Is it? I could not actually get my implementation of this idea even close to working, but I also introduced a lot of new moving parts at once, and I'm still getting the hang of debugging. This seems like it would be the most user-friendly workflow of these various approaches.
I agree this would be the most user friendly option. It will also require the most implementation effort. Basically, we need to build a XUL+HTML (or XUL+PDF) help viewer that does not allow users to "escape" and start accessing the network.
How salient are the risks of accessing the network if there are no external links in the manual and the window is opened with arguments similar to:
window.open("file://" + dir + "index.html", "_blank", "status=0,toolbar=0,location=0,menubar=0"),
?
That is, why would escaping and accessing the network be a consideration if the address bar, menubar, and toolbar aren't loaded?
On 5/28/14, 12:34 PM, Matt Pagan wrote:
How salient are the risks of accessing the network if there are no external links in the manual and the window is opened with arguments similar to:
window.open("file://" + dir + "index.html", "_blank", "status=0,toolbar=0,location=0,menubar=0"),
?
That is, why would escaping and accessing the network be a consideration if the address bar, menubar, and toolbar aren't loaded?
One possibility is that the user intentionally (or accidentally) drags a URL into the help window. There are probably several other possibilities that should be blocked. Research is needed.
There is also an issue that the Tor Launcher wizard is in a modal window that floats above all other TBB windows. A help viewer window will need to be opened as a modal window (which means users would not be able to interact with the wizard window until they close the help window). As I recall, there are annoying platform-specific differences in Firefox related to dialogs and modality. More research and design is needed here.
-- Kathy
So one the hand, it seems that adding a button to open a pdf manual in the system's default pdf viewer software is quite doable, and would not require that much development effort. However, this would also reduce the manual's accessibility, and the user experience would not be as polished.
On the other hand, having a locked down manual reader in the browser seems like it would be the most user-friendly option. However it's also apparent that creating it would require non-trivial research, design, and implementation effort. Realistically, mcs and brade would be doing most of this work, although I'd like to help out as I could. Do either of them of the time or willingness to make this a priority? If not, is Lunar willing to compromise his strategic vision for the manual in order to make sure this entire project doesn't get placed on the backburner and neglected?
Matt Pagan:
On the other hand, having a locked down manual reader in the browser seems like it would be the most user-friendly option.
Another option. The manual has no external resources and we rely on the system browser. In the Tor Browser archive, there's a symlink to a page like the following one: https://people.torproject.org/~lunar/volatile/manual/
There's probably many style and UX improvements that can be made, but you can get the idea.
Lunar:
Matt Pagan:
On the other hand, having a locked down manual reader in the browser seems like it would be the most user-friendly option.
Another option. The manual has no external resources and we rely on the system browser. In the Tor Browser archive, there's a symlink to a page like the following one: https://people.torproject.org/~lunar/volatile/manual/
There's probably many style and UX improvements that can be made, but you can get the idea.
My thoughts on this are that users may understand that Tor is not working in the browser, and then wonder how to get Tor working in the browser.
Another concern I have here is that users for whom Firefox is the default browser would be running Firefox and Tor Browser side by side if they did not close the manual when they were done reading it. I myself have accidentally visited web pages in Firefox instead of Tor Browser when I have had both browsers running at the same time, and I regularly tell users the importance of not getting their Tor Browser and regular browsers mixed up.
On the other hand, this risk could be reduced if it were possible to open the system browser with no toolbar, menubar, or navigation bar.
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
Matt Pagan:
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
My security concerns may be misplaced here, though. What do developers think of Lunar's design? Is the warning message clear enough? If others think so, I'm ok with going this route.
Matt Pagan:
Matt Pagan:
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
My security concerns may be misplaced here, though. What do developers think of Lunar's design? Is the warning message clear enough? If others think so, I'm ok with going this route.
Please, let's not rely on a non-Tor Browser for the reasons you pointed out. Even with the warning on the first page there is plenty room to shoot oneself in the foot.
Couldn't you split the tbb manual efforts a bit and having a real manual in the Tor Browser available (be it as pdf or in html) and treating the subset Lunar mentioned (whatever exactly that might be) differently? I.e. having additional help buttons in the Tor Launcher menus that are opening scrollable textboxes explaining things/offering help? The only use case that is not covered by this idea is a Tor Browser that got stuck even before Tor Launcher dialogs are showing up. Not sure how important it is to have this one covered with a manual we ship as well. IMO this should be covered by a different kind of support which is e.g. offered on the same page the user downloads the bundle from.
Georg
Georg Koppen:
Matt Pagan:
Matt Pagan:
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
My security concerns may be misplaced here, though. What do developers think of Lunar's design? Is the warning message clear enough? If others think so, I'm ok with going this route.
Please, let's not rely on a non-Tor Browser for the reasons you pointed out.
I need to understand. Are you against publishing the user manual on www.torproject.org?
Lunar:
Georg Koppen:
Matt Pagan:
Matt Pagan:
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
My security concerns may be misplaced here, though. What do developers think of Lunar's design? Is the warning message clear enough? If others think so, I'm ok with going this route.
Please, let's not rely on a non-Tor Browser for the reasons you pointed out.
I need to understand. Are you against publishing the user manual on www.torproject.org?
No.
Georg
Georg Koppen:
Matt Pagan:
Matt Pagan:
Ultimately, I wonder if relying on the system browser to display a component of the Tor Browser would violate the Proxy Obedience security requirement of the design document.
My security concerns may be misplaced here, though. What do developers think of Lunar's design? Is the warning message clear enough? If others think so, I'm ok with going this route.
Please, let's not rely on a non-Tor Browser for the reasons you pointed out. Even with the warning on the first page there is plenty room to shoot oneself in the foot.
Couldn't you split the tbb manual efforts a bit and having a real manual in the Tor Browser available (be it as pdf or in html) and treating the subset Lunar mentioned (whatever exactly that might be) differently? I.e. having additional help buttons in the Tor Launcher menus that are opening scrollable textboxes explaining things/offering help? The only use case that is not covered by this idea is a Tor Browser that got stuck even before Tor Launcher dialogs are showing up. Not sure how important it is to have this one covered with a manual we ship as well. IMO this should be covered by a different kind of support which is e.g. offered on the same page the user downloads the bundle from.
Small integrated help screens like the one Tor Launcher currently has for bridges don't give nice user experience. We can't link to a glossary or another page explaining the tradeoffs of each pluggable transport for example. I believe that's suboptimal.
Firefox online help is hosted on https://support.mozilla.org/. It appears they assume that if you can't connect… well you need to find a way to fix that first. Having the manual hosted like is great for developers as it gives more flexibility: you can fix problems, give new workarounds or update translations after releasing the packages.
Only having the manual accessible on a website would not be a good solution for the Tor Browser because we want to help users get online or circumvent censorship. I believe users should be able to learn which pluggable transports to choose and that they need to disable WebRoot Internet Security even when they got the Tor Browser through some friend's USB stick. They need to learn how they could use GetTor to get an updated version or reach out for support.
But I believe the manual should be accessible on a website for the reasons listed above (translations, updating known issues), search engines, and also because it will explain things like verification and installation.
This is where I have a hard time understanding the fear of using a system browser. How much difference does it make to access the manual through a search on Google or a click on an icon in a file browser?
On 5/28/14, 8:42 PM, Matt Pagan wrote:
So one the hand, it seems that adding a button to open a pdf manual in the system's default pdf viewer software is quite doable, and would not require that much development effort. However, this would also reduce the manual's accessibility, and the user experience would not be as polished.
On the other hand, having a locked down manual reader in the browser seems like it would be the most user-friendly option. However it's also apparent that creating it would require non-trivial research, design, and implementation effort. Realistically, mcs and brade would be doing most of this work, although I'd like to help out as I could. Do either of them of the time or willingness to make this a priority?
Time is the issue. Currently, our top priorities are bug #4234 (updater), fixing critical Tor Launcher issues, and assisting with Firefox patches (a new ESR release is coming soon from Mozilla, which will cause a spike in workload for all TBB developers, including us).
Matt Pagan:
Hello tbb-devs. Here are a few divergent thoughts on presenting the Tor Browser manual in a sensible manner for Tor Browser users. Please provide feedback regarding whether any of these seem reasonable/feasible.
Concerns have been raised about both the PDF and HTML formats. However, concerns about the PDF format are not blockers to deployment, whereas concerns about the HTML format have been.
So far, mikeperry, mcs, brade, and gk have all expressed favorable opinions about using the PDF format. Ultimately the developers have and continue to put in the most work to make the Tor Browser what it is, so I think respecting their vision for the Tor Browser makes sense.
I'm now of the opinion that going with a PDF manual for some or all of the content presents us with the clearest path forward. I think this would be some variation of presentation mode 1). Of course this doesn't mean that we can't host an online version of the manual as well.
-
Georg Koppen -
Kathleen Brade -
Lunar -
Mark Smith -
Matt Pagan -
Roger Dingledine